Перейти к содержанию

Участие в развитии стандартов

Изменения публикуются в корпоративном GitLab. Источник правды, формат требований, уровни обязательности и правила версионирования определены в README.md. Инструкции для ИИ-агентов находятся в AGENTS.md.

Перед изменением

  1. Создайте отдельную ветку от актуальной защищённой ветки.
  2. Прочитайте все документы изменяемой области и найдите связанные ID.
  3. Определите регулируемый риск, область применения и объективный способ проверки.
  4. Проверьте, нельзя ли получить тот же результат уточнением существующего требования без добавления новой обязанности.

Состав merge request

Merge request должен:

  • ограничиваться одной связной целью;
  • явно перечислять добавленные и изменённые ID;
  • отличать изменение смысла, уровня или области от редакционной правки;
  • обновлять связанные схемы, таблицы, catalog и примеры;
  • содержать результаты выполненных проверок и известные ограничения;
  • ссылаться на ADR или согласование, когда его требует стандарт.

Пример не является production-ready реализацией. Требования к его оформлению и использованию определены DOC-CLR-006 и DOC-CLR-007.

Изменения на границе слоёв

Если merge request меняет архитектурный контракт и его платформенную реализацию, в описании нужно перечислить затронутые архитектурные и инфраструктурные ID. Оба слоя, технологический profile, каталоги применимости и проверки обновляются атомарно.

Архитектурный документ остаётся единственным источником семантики поведения приложения. Инфраструктурный документ ссылается на архитектурный ID и описывает только deployment-, runtime- или platform-механизм. Платформенное изменение, не меняющее наблюдаемое поведение приложения, может затрагивать только docs/infrastructure/.

Проверка

Из корня репозитория выполните:

scripts/check-docs.sh
scripts/build-docs.sh
docker build --target build .

Первая команда проверяет Markdown, структуру требований, ID, ссылки, JSON Schema и применимость. Вторая выполняет локальную строгую сборку MkDocs. Docker build повторяет проверки и сборку сайта в воспроизводимом окружении.

Если проверка не запускалась или завершилась ошибкой, это должно быть явно указано в merge request.

GitLab CI создаёт pipeline только для default branch. В рабочих ветках и merge request обязательные проверки выполняются локально до передачи изменения на review; отсутствие branch pipeline не считается подтверждением результата.

Версионирование и лицензия

Каждый commit, публикуемый как новое состояние main, получает новый аннотированный release-тег по Semantic Versioning согласно README.md. Публикующий должен отправить commit и тег атомарно; рабочие ветки до попадания в main не тегируются. Изменения, принятые в репозиторий, распространяются по условиям MIT License.

Подготовленный diff в актуальном main публикуется командой python3 scripts/release.py --level patch|minor|major --execute. Level выбирается по семантике изменения до запуска helper.