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

Що потрібно зробити спочатку

Перед тим як приступати до публікації модулів, необхідно пройти кілька підготовчих етапів.

Переконайтеся, що ви вже:

1. Ознайомилися з перевагами партнерської програми OkayCMS

2. Ознайомилися з умовами та правилами співпраці

3. Подали заявку на партнерство через офіційний сайт OkayCMS

4. Отримали зворотний зв'язок від служби підтримки

5. Зареєструвалися в маркетплейсі як партнер

Після виконання цих кроків ви отримаєте доступ до кабінету партнера та зможете переходити до підготовки й публікації модулів.

Далі у цій інструкції розглянемо повний процес: від підготовки репозиторію до появи модуля в маркетплейсі OkayCMS.

Як працює публікація модулів

Нижче показано загальну схему роботи публікації модулів у OkayCMS.

Процес починається з чистої версії OkayCMS, після чого для кожного модуля створюється окрема гілка. У цій гілці виконується вся розробка та внесення змін. Після завершення роботи створюється версія модуля через Git tag, а маркетплейс автоматично отримує нову версію з репозиторію.

1. master Чиста версія OkayCMS без сторонніх модулів та змін. Вона використовується як база для створення нових модулів.

2. Створення гілки модуля Для кожного нового модуля створюється окрема Git-гілка. У ній зберігається весь код, який стосується лише цього модуля.

3. Розробка модуля Етап створення функціоналу, логіки роботи, шаблонів, налаштувань та необхідних файлів модуля.

4. Commit Фіксація виконаних змін у Git із коротким описом виконаної роботи.

5. Git tag Створення окремої версії модуля. Саме Git tag використовується маркетплейсом для створення нової версії.

6. Bitbucket Репозиторій, у якому зберігається код модуля, історія змін та всі його версії.

7. modules.okay-cms.com Сервіс автоматично перевіряє репозиторій, знаходить нові теги та імпортує нові версії модулів.

8. Маркетплейс OkayCMS Після обробки модуль або його нова версія стає доступною користувачам у маркетплейсі.

Необхідні інструменти та знання

Перед початком роботи переконайтеся, що у вас підготовлене необхідне робоче середовище та є базові знання для роботи з модулями OkayCMS.

Для роботи знадобляться:

Перше налаштування репозиторію

Крок 1. Склонуйте OkayCMS

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

git clone [email protected]:OkayCMS/OkayCMS.git <folder_name>

Наприклад:

git clone [email protected]:OkayCMS/OkayCMS.git okay_modules

Або, якщо ви вже перебуваєте в потрібній порожній папці:

git clone [email protected]:OkayCMS/OkayCMS.git .

Крапка означає клонування репозиторію в поточну директорію.

Крок 2. Видаліть історію Git

Перейдіть у директорію проєкту:

cd <folder_name>

Після цього виконайте:

rm -rf .git

Це від'єднає репозиторій від офіційної історії OkayCMS.

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

git init

Після виконання буде створено директорію .git.

Важливо: без цього кроку команди git add, git commit та git push не працюватимуть.

Крок 4. Створіть локальний конфіг

Створіть файл:

config/config.local.php

Приклад:

<?php $config = [ 'db_host' => 'localhost', 'db_user' => 'root', 'db_pass' => '', 'db_name' => 'okaycms', ];

Файл використовується для підключення локальної бази даних.

Крок 5. Імпортуйте базу даних

Імпортуйте файл:

1DB_changes/okay_clean.sql

Для імпорту можна використовувати phpMyAdmin, Adminer або TablePlus.

Крок 6. Встановіть залежності

composer install

Команда встановить усі необхідні бібліотеки для роботи OkayCMS.

Створення репозиторію Bitbucket

Після підготовки локального середовища необхідно створити власний репозиторій у Bitbucket. Саме він буде використовуватися для зберігання коду модулів, ведення історії змін та автоматичної інтеграції з маркетплейсом OkayCMS.

Під час створення репозиторію важливо одразу вказати правильні параметри. Неправильні налаштування на цьому етапі можуть призвести до проблем із Git, webhook або автоматичним імпортом модулів у маркетплейс.

На цьому етапі ви:

1. Створите новий репозиторій у Bitbucket

2. Налаштуєте його початкові параметри

3. Вкажете правильну основну гілку

4. Підготуєте репозиторій до подальшої розробки та публікації модулів.

Особливу увагу зверніть на гілку master.

У репозиторії OkayCMS гілка master використовується як база для створення модулів і повинна містити лише чисту версію OkayCMS без сторонніх змін, тестового коду та файлів модулів.

Саме від гілки master у майбутньому створюватимуться окремі гілки модулів, тому при створенні репозиторію необхідно використовувати:

Default branch → master

Не рекомендується використовувати гілку main, оскільки документація, процес публікації модулів та механізми оновлення в OkayCMS орієнтовані саме на master.

Параметри репозиторію повинні бути такими:

• Include README → No
• Include .gitignore → No
• Default branch → master

README та .gitignore створювати не потрібно, оскільки вони вже присутні у вихідному коді проєкту або будуть додані пізніше за необхідності.

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

Перший commit чистої OkayCMS

Після створення репозиторію в Bitbucket необхідно додати до нього чисту версію OkayCMS та виконати перший commit у гілку master.

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

Виконайте команди:

git add . git commit -m "OkayCMS 4.5.2" git push -u origin master

На цьому етапі ви:

1. Додасте всі файли OkayCMS до Git

2. Створите перший commit із чистою версією системи

3. Відправите код у репозиторій Bitbucket

4. Створите базову гілку master для подальшої розробки модулів.

Навіщо це потрібно?

У гілці master повинна зберігатися лише чиста версія OkayCMS без будь-яких змін та додаткових файлів. Саме від неї в майбутньому створюватимуться окремі гілки модулів.

Після виконання команд рекомендується перевірити репозиторій у Bitbucket та переконатися, що в ньому знаходиться лише чиста структура файлів OkayCMS.

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

Створення гілки модуля

У OkayCMS кожен модуль розробляється в окремій Git-гілці, яка створюється від гілки master. Такий підхід дозволяє ізолювати код різних модулів, спрощує підтримку проєкту та виключає випадкове потрапляння коду модуля в основну гілку системи.

Перед створенням нової гілки переконайтеся, що ви знаходитесь у гілці master:

git checkout master

Після цього створіть нову гілку для модуля:

git checkout -b popup_cart

Де popup_cart — це назва вашого модуля та майбутньої гілки.

На цьому етапі ви:

1. Перейдете в чисту гілку master

2. Створите окрему гілку для нового модуля

3. Підготуєте середовище для подальшої розробки

4. Відокремите код модуля від інших проєктів та модулів

Приклади назв гілок:

• popup_cart — спливаючий кошик;
• set — комплекти товарів;
• fast_order — швидке замовлення.

Навіщо це потрібно?

Кожен модуль у маркетплейсі OkayCMS повинен мати власну окрему гілку. Це дозволяє незалежно розробляти, оновлювати та публікувати модулі без впливу на інші гілки репозиторію.

Після створення гілки можна переходити безпосередньо до розробки модуля та додавання його файлів у структуру OkayCMS.

Структура файлів модуля

Усі файли модуля повинні розміщуватися виключно всередині каталогу:

Okay/Modules/<Vendor>/<ModuleName>/

Наприклад:

Okay/Modules/VendorName/PopupCart/ Okay/Modules/Partner/PopupCart/

Саме така структура використовується в OkayCMS та підтримується маркетплейсом під час перевірки, імпорту та встановлення модулів.

На цьому етапі ви:

1. Створите правильну структуру каталогів для модуля

2. Відокремите файли модуля від ядра OkayCMS

3. Забезпечите сумісність із маркетплейсом

4. Підготуєте модуль до подальшої розробки та публікації

Навіщо це потрібно?

Розміщення всіх файлів модуля в каталозі Okay/Modules дозволяє:

• легко встановлювати модуль;
• легко видаляти модуль;
• не змінювати ядро системи;
• уникати конфліктів під час оновлення OkayCMS;
• забезпечити коректну роботу маркетплейсу.

Правильне розташування файлів:

Усі файли, шаблони, налаштування, контролери, сутності та службові файли модуля повинні знаходитися лише всередині каталогу:

Okay/Modules/<Vendor>/<ModuleName>/

Таке розташування порушує структуру проєкту, ускладнює підтримку модуля та може призвести до помилок під час оновлення системи.

Дотримання структури Okay/Modules/<Vendor>/<ModuleName>/ є стандартом розробки модулів для OkayCMS та забезпечує їх коректну роботу в маркетплейсі.

Версія модуля

Кожен модуль повинен містити інформацію про свою поточну версію. Для цього використовується файл module.json, який знаходиться в каталозі ініціалізації модуля.

Файл повинен знаходитися за шляхом:

Okay/Modules/<Vendor>/<ModuleName>/Init/module.json

Приклад вмісту файлу:

{ "version": "1.0.0" }

На цьому етапі ви:

1. вкажете поточну версію модуля

2. підготуєте модуль до публікації в маркетплейсі

3. налаштуєте коректне відстеження релізів

4. забезпечите сумісність із механізмом оновлень OkayCMS

Навіщо це потрібно?

Маркетплейс OkayCMS використовує версію з файлу module.json для визначення поточного релізу модуля. Під час імпорту маркетплейс перевіряє відповідність версії та Git tag.

Важливо:

Значення поля version у файлі module.json повинно повністю збігатися з версією, яка використовується в Git tag.

Правильно:

module.json { "version": "1.0.0" } Git tag popup_cart_1.0.0

Неправильно:

module.json { "version": "1.0.0" } Git tag popup_cart_0.9.9 module.json { "version": "1.0.0" } Git tag popup_cart_1.0.1

Формат Git tag є обов'язковим:

<branch_name>_<version>

Наприклад:

popup_cart_1.0.0

Не рекомендується використовувати:

• 1.0.0
• v1.0.0
• master_1.0.0

Інші формати тегів не підтримуються маркетплейсом OkayCMS.

Після налаштування версії можна переходити до створення першого релізу модуля та публікації Git tag.

Правила версій

Для версіонування модулів у OkayCMS використовується формат:

MAJOR.MINOR.PATCH

Наприклад:

1.0.0

Кожна цифра у версії має своє призначення та змінюється залежно від типу внесених змін.

Приклад розвитку версії:

1.0.0 → 1.0.1 → 1.0.2 → 1.1.0 → 1.2.0 → 2.0.0

Важливо: версія у файлі module.json повинна збігатися з версією Git tag.

{ "version": "1.1.0" } popup_cart_1.1.0

Якщо версії не збігаються, маркетплейс не зможе коректно визначити новий реліз модуля.

Публікація першої версії

Після завершення роботи:

git add .

git commit -m "Перша версія"

git push

Створіть тег:

git tag popup_cart_1.0.0

git push origin popup_cart_1.0.0

Навіщо:

Маркетплейс використовує Git tag для створення нової версії.

Оновлення OkayCMS у модулі

Оновлення виконується тільки через merge.

Перейдіть:

git checkout popup_cart

Виконайте:

git merge master

Не можна:

❌ копіювати файли вручну
❌ оновлювати ядро напряму
❌ замінювати файли OkayCMS

Демо-контент

Для демо використовується:

1DB_changes/demo.sql

Не можна:

1DB_changes/okay_clean.sql

У demo дозволяється:

✅ товари
✅ банери
✅ категорії
✅ сторінки
✅ зображення

Не можна:

❌ ok_managers
❌ ok_settings
❌ ok_modules

README для користувача

Рекомендується створити:

Okay/Modules/<Vendor>/<ModuleName>/README.md

У ньому бажано описати:

• встановлення
• налаштування
• необхідні зміни шаблону
• параметри модуля

Підключення маркетплейсу

SSH ключ

Перейдіть:

Repository settings
→ Access keys

Додайте SSH ключ, який надає команда OkayCMS.

Webhook

Перейдіть:

Repository settings
→ Webhooks

Додайте:

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

Після цього маркетплейс автоматично:

✅ побачить нову версію
✅ імпортує модуль
✅ оновить сторінку модуля

Що допоможе уникнути помилок

Часті помилки

❌ створено main замість master

❌ тег створений до commit

❌ версія в module.json не збігається з тегом

❌ модуль потрапив у master

❌ SSH ключ доданий не в той репозиторій

❌ webhook відкривається вручну

❌ demo.sql доданий у master

Корисна рекомендація

Якщо ви публікуєте модуль вперше:

1. Створіть тестову копію сайту.
2. Перевірте встановлення модуля з архіву.
3. Перевірте оновлення через Git tag.
4. Переконайтеся, що README містить інструкцію.

Це значно зменшує кількість помилок під час першої публікації.