Методика

Материал из Course Orchestra
Перейти к: навигация, поиск

Методика работы с исходными кодами решений на платформе КУРС

Общие термины

Решение на платформе КУРС представляет собой набор папок библиотек и перспектив, о чём будет сказано далее. Любое решение на платформе КУРС:

  1. Использует систему Apache Subversion для контроля версий исходного кода решения.
  2. Регистрируется в online-системе регистрации решений на платформе КУРС.

В отношении кода, написанного для платформы КУРС, необходимо использовать следующие термины:

  1. Системная библиотека (system library) – код, который идентичен во всех проектах. Решение должно всегда смотреть на последнюю версию библиотеки (рекомендуемый механизм ссылки на конкретную ревизию системного решения предназначен только для того, чтобы обновление версии было контролируемо). Системная библиотека располагается в папке common.sys.
  2. Типовое решение (template solution) – код, который берётся за основу при внедрении в конкретной организации. При внедрении типового решения под конкретного заказчика заводится новая ветка кода (SVN branch). Задачей разработчика, использующего код типового решения в своем проекте является периодические сливание (merge) кода из типового решения, а также, по возможности, доработка самого типового решения.
  3. Пользовательское решение (custom solution) – код, созданный для решения задач конкретного заказчика. Данный код может использовать как код системных решений, так и код типовых решений.

Структура папки пользовательских данных Showcase

Папкой набора пользовательских данных (содержащей папки перспектив и библиотек) будем называть корневую папку, на которую  ссылается Showcase в свойстве "showcase.rootpath.userdata". Это свойство задается там, где задается контекст запуска web-приложения на Showcase (например, для Tomcat это файл catalina/localhost/имя_web_приложения.xml). Имя у папки может быть произвольное (например, brs, kurs и т.п.). Папка может лежать в любом месте на диске, главное, чтобы к ней имел полный доступ (на чтение и на запись) сервер приложений или контейнер сервлетов (JBoss, Tomcat, Glassfish и т.д.). По сути, под папкой набора пользовательских данных мы понимаем пользовательское решение (ad hoc solution).

В папке набора пользовательских данных находятся папки перспектив и библиотек (см. рис. 1). Файлы общих настроек generalapp.properties и скриптов Челесты должны находиться в корневом каталоге папки набора пользовательских данных (см. рис. 1).

Перспектива – это единица деления интерфейса Showcase, которая отвечает за отображение определенных наборов интерфейсных элементов пользователю. Для того чтобы у пользователя веб-приложения была показана определенная перспектива (набор элементов Showcase) необходимо в строке url указать параметр userdata=название_перспективы или perspective=название_перспективы, например:

 http://localhost:8080/Showcase?perspective=название_перспективы

В названии перспективы не должно быть строчных букв и русских символов, а также пробелов. Название перспективы должно полностью соответствовать названию папки, где перспектива находится. В целом, перспектива и то, что мы понимали ранее под папками юзердат, идентичны. В дальнейшем, после переходного периода, от параметра userdata=название_перспективы мы откажемся, перейдя на параметр perspective=название_перспективы. В папке набора пользовательских данных может содержаться неограниченное число папок с перспективами, однако всегда должна присутствовать перспектива по умолчанию с названием default. Название перспектив не может начинаться со слова common.

Если источником данных в решении является celesta и необходимо использовать системные решения (system solution) платформы КУРС (security, common, workflow, dirusing и т.д.), то в папке набора пользовательских данных обязательно должна находиться папка common.sys. Эта папка содержит в себе структуру, полностью аналогичную структуре сегодняшней папки general (внимание! В папке набора пользовательских данных теперь папки general не будет). Для папки common.sys предлагается использовать название системная библиотека, поскольку она содержит в себе не только celesta-скрипты, но и остальные файлы (js, css, plugins, resources, libraries), то есть, по сути, системное решение (не только скрипты, но и интерфейсные файлы и др., необходимые для корректной работы системных гранул). В папке набора пользовательских данных папка системной библиотеки может быть только одна и ее название жестко фиксировано – common.sys. Если в решении не используются системные решения, то наличие папки common.sys не обязательно.

Помимо системных решений, находящихся в системной библиотеке, в пользовательском решении могут использоваться и дополнительные библиотеки, которые реализуют общий для пользовательского решения функционал. Такие библиотеки содержат в себе реализацию интерфейса и логики типовых функций. Они могут содержать элементы пользовательского решения, а также элементы типовых решений (template solutions), используемых в конкретном пользовательском решении. Структура папок библиотек аналогична папке системной библиотеки (она может содержать в себе различные файлы и скрипты Celesta). Папки библиотек должны находиться в корневом каталоге папки набора пользовательских данных, а их название должно начинаться со слова common и не содержать пробел (рекомендуется использовать название следующего вида common.obfi).

Схематично структура папки набора пользовательских данных изображена на рисунке 1.

UserDataFolder.png

Рис. 1. Схематическое изображение структуры папки набора пользовательских данных

Разработка и использование системной библиотеки и типовых решений

Системная библиотека ведётся разработчиками платформы КУРС на SVN по адресу https://share.kurs-it.ru/svn/grains/celestabasic/trunk. В этот проект помещается только функциональность, которая может быть потенциально полезна во всех проектах и внедрениях, и не помещается специфичная для конкретного внедрения функциональность. Используя SVN для хранения исходного кода решений, разработчикам решений следует использовать функциональность SVN Externals для указания ссылки на гранулу general. При этом можно пользоваться той особенностью SVN, что SVN External может указывать как на Operative Revision (т. е. самую свежую ревизию), так и на Peg Revision (т. е. вполне определённую ревизию, информацию про Operative и Peg Revisions см. в SVNBook).

Разработка типовых решений производится группами разработчиков соответствующих решений (решения для банков, решения для гос. структур и т. п.) Типовые решения регистрируются в системе регистрации решений на платформе КУРС. При разработке пользовательского решения под каждое типовое решение заводится branch на Subversion.

Итак, резюмируя сказанное, имеем:

  1. для системной библиотеки используем механизм externals в Subversion
  2. для типовых решений используем механизм branches в Subversion.

Cоздание и разработка нового типового или пользовательского решения

Создавая типовое или пользовательское решение, необходимо выполнить следующее:

  1. Завести на Subversion систему папок userdata решения.
  2. Используя функционал SVN externals, указать ссылку на https://share.kurs-it.ru/svn/grains/celestabasic/trunk, так что папка common.sys чекаутится из репозитария КУРС. При этом разработчик указывает в качестве Peg Revision самую свежую версию существующего кода. В дальнейшем заботой разработчиков решения является увеличение Peg Revisions кода системной библиотеки и проверка того, что новые версии являются совместимыми с кодом решения. Естественно, возможен вариант, когда решение зависит от вполне конкретной ревизии системной библиотеки, и эта ревизия вообще никогда не увеличивается.
    Важная информация
    НЕДОПУСТИМО механически копировать код системной библиотеки в свой репозитарий, создавать независимые, оторванные от мейнстримной, версии системной библиотеки, т. к. это лишает возможности как разработчика решения получать оперативные обновления от сообщества платформы КУРС, так и лишает сообщество возможности получать идеи/апдейты от разработчиков решений.
  3. Следует зарегистрировать новое решение на странице... (TODO: следует проработать систему регистрации решений на платформе КУРС, в которой указано: название проекта, краткое описание, контактные лица, а также перечень названий гранул – для того, чтобы соблюсти глобальную уникальность названий гранул. Это должен быть аналог системы PyPl, где люди регистрируют проекты на языке python, для достижения глобальной уникальности имён пакетов.)

Контроль версий и выпуск релизов

Для контроля версий все указанные в п. 1 проекты используют систему Subversion. Использование системы Subversion является частью данной методики.

Каждый из проектов заводится в своём репозитарии Subversion со стандартной структурой trunk-branches-tags. Система trunk-branches-tags используется для поддержки выпусков релизов проектов в соответствии с методикой, описанной в SVNBook. Общий поток выпуска релизов показан на диаграмме:

M2.png

Изображённый на диаграмме пример следует интерпретировать следующим образом:

  1. Система развивалась и тестировалась в папке trunk и в какой-то момент принято решение, что некоторая вполне конкретная ревизия заслуживает выпуска в виде релиза под номером 4.1. В этот момент весь проект копируется в папку tags/4.1, пользователи уведомляются о релизе.
  2. Вся новая функциональность продолжает разрабатываться в папке trunk.
  3. Вскоре в релизе 4.1 обнаруживаются ошибки и принимается решение создать багфикс-релиз. В этот момент содержимое папки 4.1 перемещается из tags/4.1 в branches/4.1 и там начинает вестись работа по исправлению ошибок.
  4. В момент, когда ошибки исправлены, мы осуществляем релиз 4.1.1, копируя содержиvое папки branches/4 в папку tags/4.1.1
  5. Для того, чтобы исправления ошибок не были потеряны в основной ветке, происводится merge исправлений в trunk.
  6. По мере обнаружения ошибок может понадобится несколько minor releases, все они в итоге попадают в tags.
  7. Тем временем в trunk готовится очередной major release.

Процесс развития решения и взаимодействие с системной библиотекой

В процессе работы над решением возможны следующие сценарии:

1) Код системной библиотеки обновился и больше не совместим с решением. Данная проблема не возникает внезапно и неуправляемо, так как мы используем external-ссылку на вполне определённую ревизию системных гранул, и если эту ссылку никогда не обновлять, то код системной библиотеки никогда не обновится. Если возникает желание проапгрейдить системную библиотеку, то это делается разработчиком решения осознанно: он начинает с того, что апгрейдит у себя external-ссылку на более свежую ревизию системной библиотеки, приводит свой код в соответствие с новой версией библиотеки и коммитит всё вместе.

Разработчики системной библиотеки обязаны обновлять код с максимальной осторожностью, сохраняя обратную совместимость. Если без изменений, нарушающих обратную совместимость, обойтись нельзя, разработчики системной библиотеки объявляют о таких изменениях внятно и заранее, чётко аргументируя необходимость таких изменений.

2) Разработчик столкнулся с ошибкой в системной библиотеке и требуется её исправление. Тут возможны два варианта.

  • Если разработчик решения имеет доступ на запись в репозитарий системной библиотеки, то тогда проблема решается максимально быстро и удобно: разработчик исправляет ошибку прямо в своей локальной копии кода и делает commit в репозитарий системной библиотеки, при этом исправление ошибки получают все пользователи системной библиотеки во всех решениях на платформе КУРС. Естественно, воспользоваться они этим исправлением смогут лишь тогда, когда увеличат номера ревизий в своих external-ссылках на системную библиотеку.
  • Если разработчик не имеет доступа на запись к репозитарию системной библиотеки, но в состоянии исправить ошибку самостоятельно, то проблему следует решить, прислав текст кода, исправляющего ошибку, ответственному лицу или в крайнем случае любому человеку, имеющему доступ на запись в системную библиотеку. Перечень ответственных лиц по системной библиотеки должен быть доступен в открытом и актуализированном источнике, по сути – в том же реестре решений на платформе КУРС, о котором говорилось выше. Ответственное лицо обязано быстро среагировать и вмёрджить исправление ошибки в системную библиотеку. В самом худшем случае это не должно занимать больше недели, а до того момента разработчики решения вполне могут пользоваться временным решением (рассылая друг другу исправленные системные модули хоть по электронной почте, если над решением работает несколько человек, но в подавляющем большинстве случаев от исправления зависит всего лишь один человек, который может временно пожить на локально исправленном коде).
  • Если разработчик не в состоянии исправить ошибку самостоятельно, он поднимает Trac тикет (https://share.curs.ru/trac/grains).

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

3) Разработчик столкнулся с необходимостью изменить функциональность системных библиотек. Здесь необходимо чётко, раз и навсегда понимать: в системных библиотеках не должно содержаться кода, специфичного для решения (за исключением настроечных файлов). Работа с настроечными файлами в Subversion должна быть подчинена стандартному приёму использования шаблона файла (.template-файла), как описано, например, здесь или здесь. Поэтому, если речь идёт о необходимости изменения функциональности системной библиотеки, то это должно быть такое изменение, которое потенциально полезно всем пользователям платформы КУРС. В этом случае мы поступаем так же, как с исправлением ошибки: либо правим системную библиотеку напрямую (если есть такие права), либо присылаем обновление по электронной почте ответственному лицу, либо заносим запрос в Trac.