Инструкция для разработчиков по оформлению модулей

Категории
Оглавление
  1. Как происходит размещение дополнения в маркетплейсе OkayCMS:
  2. Как оформлять модуль для OkayCMS
  3. Как ведется версионность дополнений
  4. Что необходимо для публикации дополнения:

Прежде всего, хотим сказать спасибо за интерес к разработке для OkayCMS. Мы верим, что совместно с нашим комьюнити сможем поднять систему на новый уровень. Все мы сталкиваемся с разными задачами и потребностями заказчиков. Делясь своими наработками, можно сильно расширить возможности CMS и, конечно, заработать неоднократно на дополнении, которое принесло прибыль однажды, а после хранится в забвении где-то на жестком диске. Мы сделали систему с открытым кодом, чтобы как можно больше талантливых людей смогли подключиться к процессу разработки. Мы будем рады, если вы пополните их ряды.

А теперь от высоких вещей перейдем к применимым на практике.

 

Как происходит размещение дополнения в маркетплейсе OkayCMS:

Вы присылаете материалы, оформленные в соответствии с требованиями, на info@okay-cms.com. О требованиях к оформлению мы расскажем ниже.

Модератор из нашей команды проверяет работу модуля до 3-х рабочий дней и выкладывает его на Git. Если в ходе рассмотрения возникают какие-то вопросы или замечания, мы связываемся с вами по контактному e-mail.

Если все в порядке, контент-менеджер размещает модуль в маркетплейсе. Как только дополнение опубликовано на сайте, оно доступно к заказу.

 

Как оформлять модуль для OkayCMS

Нужно понимать, что скорость размещения дополнения на официальном сайте напрямую зависит от того, насколько правильно вы его оформите. Мы предлагаем требования, чтобы унифицировать процесс и не затягивать проверку. Если их проигнорировать, дополнение, скорее всего, вернется на доработку, т.к. нашим разработчикам есть на что тратить время.

  1. Каждому разработчику присваивается уникальный префикс (далее по тексту - "vendor"). Он используется для составления лейбла модуля, для формирования комментариев модуля.

Узнать префикс можно, написав на почту info@okay-cms.com. Если вы ещё не делали дополнения для нас, можете придумать его самостоятельно. Обычно он совпадает с названием компании/ником разработчика и т.п. Напишите латиницей, поставьте нижнее подчеркивание между словами и пришлите на ту же почту, чтобы мы проверили, нет ли совпадений с существующими. Если префикс окажется неуникальным, составим для вас другой.

  1. Комментарии нужно использовать только блочные. Ими вы отмечаете начало и конец изменений в коде. Все комментарии обязательно должны начинаться с префикса разработчика.

Пример для PHP и JS: /*vendor_module_name*/.../*/vendor_module_name*/

для Smarty: {*vendor_module_name*}...{*/vendor_module_name*}


Между словами в комментариях ставьте нижнее подчеркивание – использование пробелов внутри комментариев не допускается.

  1. SQL-файл дополнения называйте так же, как и комментарий дополнения, по схеме vendor_module_name.sql.

Все SQL-запросы должны быть 100% рабочими для стандартной версии OkayCMS. Запросы в файле разделяйте точкой с запятой.

  1. Недопустимо вырезать код, не обозначив его комментарием.
    нельзя вырезать код

Правильным будет закомментировать код и добавить свой.
нужно закомментировать

Еще пример, как делать плохо:

плохой код

хорошо:

хороший код


Отмечать нужно не всю строку, в которую вносились изменения, а непосредственно изменения.


Так плохо:

не отмечать всю строку

а так хорошо:

отмечать только изменения


Если же синтаксис не позволяет обозначить комментарием в рамках одной строки только новый код или код становится нечитабельным, допускается закомментировать всю строчку кода, отметив это комментарием, и добавить свою с изменениями.

  1. При расширении списков, на подобии этих, добавляйте новые элементы только в конец списка.
    оформление списков

  2. В переводах желательно добавлять свои переводы одним пакетом, а не разбивать по файлу.
    переводы

  3. Недопустимо заменять один файл другим, просто указав это где-то в инструкции. В таких случаях нужно добавить файл и подключить его вместо дефолтного, а подключение обозначить комментариями.

Как ведется версионность дополнений

  1. Мы присваиваем версию модулю, совмещая версию самого дополнения и версию OkayCMS, для которой оно разработано. Т.е. версия модуля состоит из двух чисел.

Например: module_1.0_for_OkayCMS_2.2.2 (где module – название дополнения)

  1. Когда обновляется OkayCMS внутри модуля и модуль обновляется только под требования системы, версия модуля не меняется.

Если обновляется дополнение (исправление/добавление функционала), увеличивается версия именно дополнения.

  1. Не допускается обновление версии модуля и версии OkayCMS одним коммитом.

Если нужно обновить версию модуля (пофиксить баг) и версию OkayCMS, для которой модуль предназначен, желательно первым обновить модуль, затем – CMS внутри модуля. Так мы получим обновленный модуль для двух версий системы.

Что необходимо для публикации дополнения:

  1. Документ .docx со следующей информацией:
  • Название модуля – должно быть понятным и максимально отражать функционал, чтобы заинтересовать посетителей маркетплейса.
  • Текст описания – мы не требуем опусов и запредельной грамотности, просто расскажите, зачем это дополнение и как с ним работать.
  • Условия установки – самостоятельная, техподдержкой OkayCMS, разработчиком. Если модуль будете ставить вы, то обязуетесь связаться с клиентом не позднее, чем через 3 дня после заказа, иначе он будет удален из маркетплейса.
  • Условия поддержки – не оказывается, только по почте, по почте и по телефону.
  1. Дополнительные материалы для размещения на сайте:
  • Скриншоты дополнения – они будут выводиться как фото товара, а также в описании. С их помощью клиент должен наглядно увидеть изменения, которые привнесёт дополнение на сайт, в админку, уведомления и т.д., и понять, за что он платит деньги.
    скриншоты в карточке дополнения
  • Видеообзор – нужен, чтобы показать, как с модулем работать.
  • Ссылка и доступы к демосайту (если есть) – когда клиент понимает, что получит, легче расстается с деньгами.
  • Иконка 95х95 px – чтобы дополнение выглядело презентабельно в маркетплейсе.

Наличие этих материалов не обязательно, но очень желательно, т.к. в разы увеличивает вероятность покупки.

  1. Zip-архив с самим дополнением.
  • Назовите архив в формате modulename_moduleversion_for_OkayCMS_cmsversion.zip

Например: sale_timer_1.0_for_OkayCMS_1.2.0.zip

  • В корень положите файл readme.txt, где описан комментарий, которым отмечены все изменения в коде, и указаны файлы, измененные полностью или созданные вами.
  • Если необходимо изменение БД, предоставьте также файл с SQL-запросом в формате .sql.

Приложите всё это к письму модератору на info@okay-cms.com. В письме укажите цену на свой модуль, вы будете получать 50% от каждого заказа.

That's All Folks! И помните, вы наш самый важный ресурс!

Комментарии 3
OkayCMS
06.11.2018, 13:09
Для сравнения мы используем phpstorm
Дмитро
05.11.2018, 20:30
Дійсно, а що за текстовий редактор для порівнювання 2 файлів в обзорі використовуєте? виглядає прикольно...
Виталий
04.11.2018, 03:17
1. Подскажите пожалуйста, как называется программа для сравнивания 2 файлов, которая приводится на скринах в статье с сравниванием кода?

2. Также была бы интересна статья или видео, как на практике работать с Git, и контролировать изменения как CMS так и своих модулей, особенно когда выходят новые версии CMS которые нужно связать с своими модулями, я полагаю Git в данном процессе помогает.

P.S. Имеются много своих правок как CMS так и своих модулей, тесно связаных и зависящих друг от друга. Стыдно признавать, но вот с Git так и не удалось полноценно научиться работать, либо просто не понял как с ним правильно взаимодействовать... и когда выпускается обновление CMS, приходиться помучатся в сравнивании файлов и переносом правок как от CMS, так и связать изменения CMS c своими модулями, так как бывает что выпускаемые новые версии CMS и внесенные изменения, затрагивают логику модуля в следствии чего, забирает много времени чтобы связать обновления CMS c своими правками либо модулями, а потом еще и протестировать.

Лично я сейчас через Notepad++ по FTP подключаюсь к хостингу, открываю код и веду разработку, мне это удобно так как приходиться работать с нескольких рабочих мест и соответственно компьютеров, и завершив кусок кода на одном устройстве, легко продолжить доработку на другом компе и без локалки, а когда выходят обновления CMS c помощью Notepad++ можно сравнить файл CMS c файлом на хостинге и перенести правки, и как я понимаю чтобы контролировать версии как CMS так и модулей можно использовать Git, вот если подскажите как в данную цепочку прикрутить Git, буду очень благодарен.

Заранее спафсибо!
Написать комментарий
Войдите в личный кабинет
Скачать OkayCMS
version 4.3.2
Подписаться на рассылку
Вы будете получать подборку полезных статей по работе с сайтом на OkayCMS, скидки на модули и шаблоны