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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

хорошо:

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

Так плохо:

а так хорошо:

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

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

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

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

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

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

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

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

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

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

1. Документ .docx со следующей информацией:

• Название модуля – должно быть понятным и максимально отражать функционал, чтобы заинтересовать посетителей маркетплейса.
• Текст описания – мы не требуем опусов и запредельной грамотности, просто расскажите, зачем это дополнение и как с ним работать.
• Условия установки – самостоятельная, техподдержкой OkayCMS, разработчиком. Если модуль будете ставить вы, то обязуетесь связаться с клиентом не позднее, чем через 3 дня после заказа, иначе он будет удален из маркетплейса.
• Условия поддержки – не оказывается, только по почте, по почте и по телефону.

2. Дополнительные материалы для размещения на сайте:

• Скриншоты дополнения – они будут выводиться как фото товара, а также в описании. С их помощью клиент должен наглядно увидеть изменения, которые привнесёт дополнение на сайт, в админку, уведомления и т.д., и понять, за что он платит деньги.
  
• Видеообзор – нужен, чтобы показать, как с модулем работать.
• Ссылка и доступы к демосайту (если есть) – когда клиент понимает, что получит, легче расстается с деньгами.
• Иконка 95х95 px – чтобы дополнение выглядело презентабельно в маркетплейсе.

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

3. 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! И помните, вы наш самый важный ресурс!