Инструкция для разработчиков по оформлению модулей
Прежде всего, хотим сказать спасибо за интерес к разработке для OkayCMS. Мы верим, что совместно с нашим комьюнити сможем поднять систему на новый уровень. Все мы сталкиваемся с разными задачами и потребностями заказчиков. Делясь своими наработками, можно сильно расширить возможности CMS и, конечно, заработать неоднократно на дополнении, которое принесло прибыль однажды, а после хранится в забвении где-то на жестком диске. Мы сделали систему с открытым кодом, чтобы как можно больше талантливых людей смогли подключиться к процессу разработки. Мы будем рады, если вы пополните их ряды.
А теперь от высоких вещей перейдем к применимым на практике.
Как происходит размещение дополнения в маркетплейсе OkayCMS:
Вы присылаете материалы, оформленные в соответствии с требованиями, на info@okay-cms.com. О требованиях к оформлению мы расскажем ниже.
Модератор из нашей команды проверяет работу модуля до 3-х рабочий дней и выкладывает его на Git. Если в ходе рассмотрения возникают какие-то вопросы или замечания, мы связываемся с вами по контактному e-mail.
Если все в порядке, контент-менеджер размещает модуль в маркетплейсе. Как только дополнение опубликовано на сайте, оно доступно к заказу.
Как оформлять модуль для OkayCMS
Нужно понимать, что скорость размещения дополнения на официальном сайте напрямую зависит от того, насколько правильно вы его оформите. Мы предлагаем требования, чтобы унифицировать процесс и не затягивать проверку. Если их проигнорировать, дополнение, скорее всего, вернется на доработку, т.к. нашим разработчикам есть на что тратить время.
- Каждому разработчику присваивается уникальный префикс (далее по тексту - "vendor"). Он используется для составления лейбла модуля, для формирования комментариев модуля.
Узнать префикс можно, написав на почту info@okay-cms.com. Если вы ещё не делали дополнения для нас, можете придумать его самостоятельно. Обычно он совпадает с названием компании/ником разработчика и т.п. Напишите латиницей, поставьте нижнее подчеркивание между словами и пришлите на ту же почту, чтобы мы проверили, нет ли совпадений с существующими. Если префикс окажется неуникальным, составим для вас другой.
- Комментарии нужно использовать только блочные. Ими вы отмечаете начало и конец изменений в коде. Все комментарии обязательно должны начинаться с префикса разработчика.
Пример для PHP и JS: /*vendor_module_name*/.../*/vendor_module_name*/
для Smarty: {*vendor_module_name*}...{*/vendor_module_name*}
Между словами в комментариях ставьте нижнее подчеркивание – использование пробелов внутри комментариев не допускается.
- SQL-файл дополнения называйте так же, как и комментарий дополнения, по схеме vendor_module_name.sql.
Все SQL-запросы должны быть 100% рабочими для стандартной версии OkayCMS. Запросы в файле разделяйте точкой с запятой.
Правильным будет закомментировать код и добавить свой.
Еще пример, как делать плохо:
хорошо:
Отмечать нужно не всю строку, в которую вносились изменения, а непосредственно изменения.
Так плохо:
а так хорошо:
Если же синтаксис не позволяет обозначить комментарием в рамках одной строки только новый код или код становится нечитабельным, допускается закомментировать всю строчку кода, отметив это комментарием, и добавить свою с изменениями.
- При расширении списков, на подобии этих, добавляйте новые элементы только в конец списка.
- В переводах желательно добавлять свои переводы одним пакетом, а не разбивать по файлу.
- Недопустимо заменять один файл другим, просто указав это где-то в инструкции. В таких случаях нужно добавить файл и подключить его вместо дефолтного, а подключение обозначить комментариями.
Как ведется версионность дополнений
- Мы присваиваем версию модулю, совмещая версию самого дополнения и версию OkayCMS, для которой оно разработано. Т.е. версия модуля состоит из двух чисел.
Например: module_1.0_for_OkayCMS_2.2.2 (где module – название дополнения)
- Когда обновляется OkayCMS внутри модуля и модуль обновляется только под требования системы, версия модуля не меняется.
Если обновляется дополнение (исправление/добавление функционала), увеличивается версия именно дополнения.
- Не допускается обновление версии модуля и версии OkayCMS одним коммитом.
Если нужно обновить версию модуля (пофиксить баг) и версию OkayCMS, для которой модуль предназначен, желательно первым обновить модуль, затем – CMS внутри модуля. Так мы получим обновленный модуль для двух версий системы.
Что необходимо для публикации дополнения:
- Документ .docx со следующей информацией:
- Название модуля – должно быть понятным и максимально отражать функционал, чтобы заинтересовать посетителей маркетплейса.
- Текст описания – мы не требуем опусов и запредельной грамотности, просто расскажите, зачем это дополнение и как с ним работать.
- Условия установки – самостоятельная, техподдержкой OkayCMS, разработчиком. Если модуль будете ставить вы, то обязуетесь связаться с клиентом не позднее, чем через 3 дня после заказа, иначе он будет удален из маркетплейса.
- Условия поддержки – не оказывается, только по почте, по почте и по телефону.
- Дополнительные материалы для размещения на сайте:
- Скриншоты дополнения – они будут выводиться как фото товара, а также в описании. С их помощью клиент должен наглядно увидеть изменения, которые привнесёт дополнение на сайт, в админку, уведомления и т.д., и понять, за что он платит деньги.
- Видеообзор – нужен, чтобы показать, как с модулем работать.
- Ссылка и доступы к демосайту (если есть) – когда клиент понимает, что получит, легче расстается с деньгами.
- Иконка 95х95 px – чтобы дополнение выглядело презентабельно в маркетплейсе.
Наличие этих материалов не обязательно, но очень желательно, т.к. в разы увеличивает вероятность покупки.
- 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! И помните, вы наш самый важный ресурс!
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, буду очень благодарен.
Заранее спафсибо!