Інструкція зі створення репозиторію модулів для OkayCMS

Крок 1. Клонування офіційного репозиторію

1. Склонуйте офіційний репозиторій OkayCMS:

    

   git clone [email protected]:sm_okay/okaycms3_module_list.git

2. Видаліть директорію .git, щоб від’єднатися від оригінальної історії:

    

   rm -rf .git

3. Ініціалізуйте репозиторій заново:

    

   git init

Крок 2. Налаштування середовища

• Створіть файл config/config.local.php (за аналогією з config/config.php) і пропишіть у ньому свої доступи до бази даних.

• Імпортуйте дамп бази з файлу 1DB_changes/okay_clean.sql.

• Виконайте встановлення залежностей:

   

  composer install

Крок 3. Ведення репозиторію

• У гілці master мають бути версії OkayCMS, для яких створюються модулі.

• Кожен коміт у master бажано підписувати версією, наприклад:

   

  OkayCMS 3.3.5 OkayCMS 3.4.1

• У репозиторії бажано підтримувати всі основні версії OkayCMS — як у офіційному репозиторії.

Крок 4. Оновлення OkayCMS у master

Щоб оновити OkayCMS у гілці master:

1. Перейдіть у master:

    

   git checkout master

2. Видаліть усі каталоги, крім:

    

   .git config/config.local.php

   (і, за потреби, .idea чи інші власні конфігурації).

3. Склонуйте офіційний репозиторій у тимчасову директорію.

4. Перейдіть у ньому на потрібну версію OkayCMS.

5. Скопіюйте файли з тимчасової директорії у ваш репозиторій модулів.

6. Імпортуйте оновлений дамп бази 1DB_changes/okay_clean.sql.

7. Знову виконайте:

    

   composer install

Крок 5. Створення модуля

1. Кожен модуль потрібно вести в окремій гілці, створеній від відповідної версії master.

2. Назву гілки варто давати за назвою модуля, наприклад:

    

   popup_cart set kit

3. У гілці дозволено розвивати лише один модуль. Гілки не зливаються між собою.

Крок 6. Структура модуля

Модуль має бути ізольованим у директорії:

Якщо для роботи модуля потрібно додати шорткод у шаблон, — додайте його у демо-версію, але основний архів модуля не має містити ці зміни.

Також обов’язково створіть інструкцію з установлення (наприклад, install instruction.md) або реалізуйте контролер, який описує процес налаштування.

Крок 7. Версійність модулів

Версія модуля складається з трьох чисел у форматі:

Щоб позначити коміт версією модуля — додайте тег:

Наприклад:

Крок 8. Оновлення OkayCMS у гілці модуля

Оновлювати OkayCMS потрібно через merge з master, а не шляхом ручних змін у коді.

Тобто:

1. Переконайтесь, що у master є потрібна версія OkayCMS.

2. У гілці модуля виконайте merge:

    

   git merge master

Мерж повинен містити два батьківські коміти — з master і з гілки модуля.

Крок 9. Створення демо-контенту

1. Демо-контент зберігається у файлі:

    

   1DB_changes/demo.sql

2. Заборонено змінювати:

    

   1DB_changes/okay_clean.sql

3. Для створення демо-контенту:

   • додайте товари, банери тощо в адмінці;

   • відкрийте Adminer або інший клієнт БД;

   • зробіть дамп лише потрібних таблиць (ті, які змінювали);

   • у стовпчику “Tables” не вибирайте жодної таблиці;

   • у стовпчику “Data” — оберіть потрібні таблиці;

   • у першому полі “Data” вкажіть:

      

     TRUNCATE+INSERT

     і формат SQL.

⚠️ Заборонено додавати у демо-дамп таблиці:
ok_managers, ok_modules, ok_settings, ok_settings_lang.

Крок 10. Робота з шаблонами

• Кожен шаблон — окрема гілка, створена від відповідної версії master.

• Назва гілки = назва шаблону.

• Шаблон має розміщуватись у:

   

  design/<theme_name>

• Для шаблонів створіть файл:

   

  design/<theme_name>/README.md

  У ньому опишіть інструкцію з налаштування (групи банерів, дії після встановлення тощо).

• Для коректного відображення на демо-маркетплейсі додайте банери у демо-контент.

Крок 11. Додавання репозиторію в маркетплейс

• У Bitbucket перейдіть у:

   

  Repository settings → Access keys → Add key

• У полі Label вкажіть будь-яке ім’я, а в полі Key вставте цей ключ:

   

  ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCqVVOY3WVlAjG9Tjy0fLVYfMUCmwkg5chA4CPmQnoJmjgH64pFu4CJlt4EjpaVr24UCvoxHugHBBo64MQ4ON6fYlfgcsSM0GT6Z1+SDun/N4jsPazuuKL+SyzwNW1enFcovHujywghnKRyLjk1kdToIMJRgWk9+desjJbswgqFO3YasYkTVWvQ8SsJVLKHrYAEEpWi7ZKS0Z9M1whNVGwP2qpWiBsCOO7B9KcvohypPwJrpMJQughVCm8i6q/nI2UkV8bc9Mwj3Wun7qZwem7ODsKr0s55OzQiig5tZbG4UmjbQwbo0OruCXgVJiykZlNoyPMvaYHdcJ5MjefdL8Df modules.okay-cms.com@s527761d7.fastvps-server.com

Крок 12. Налаштування Webhook

Щоб модулі автоматично з’являлися у системі маркетплейсу:

1. У Bitbucket відкрийте:

    

   Repository settings → Webhooks → Add webhook

2. У полі Title введіть довільну назву.

3. У полі URL вкажіть:

    

   https://modules.okay-cms.com/bitbucket/hook/initial

Готово!

Тепер ваш репозиторій готовий для розробки, тестування та публікації модулів або шаблонів у маркетплейсі OkayCMS.