Проектная документация¶
Требования применяются к документации репозитория запускаемого или
публикуемого компонента. Уровни обязательности определены в корневом
README.md.
В этом документе машинно-производимая справочная документация — предназначенный потребителю перечень операций, команд, параметров, полей, типов или допустимых значений, состав и имена которых полностью определяются машинно-читаемым публичным контрактом, схемой, аннотациями исходного кода или схемой конфигурации.
DEV-DOC-001. Корневой README¶
Уровень: MUST
Применяется к: репозиторию запускаемого или публикуемого компонента
Корень репозитория должен содержать версионируемый README.md. Документ должен
указывать назначение проекта и предполагаемых потребителей. Для каждого
запускаемого или публикуемого компонента он должен указывать идентификатор,
ответственность, путь к исходному коду или build definition и расположение
публичных контрактов, если они существуют.
README.md должен ссылаться на обязательные проверки проекта. Для запускаемого
приложения он должен ссылаться на поддерживаемый локальный сценарий по
DEV-RUN-004. Если DEV-RUN-004 неприменим к публикуемому компоненту,
README.md должен ссылаться на воспроизводимую команду его сборки или проверки
потребителем.
Подробное описание MAY находиться в другом версионируемом документе, если
README.md содержит однозначную ссылку на него. Обязательная CI-проверка
должна подтверждать наличие корневого README.md и разрешимость его локальных
ссылок.
Обоснование¶
Единая человекообнаружимая точка входа сокращает время поиска назначения, границ и воспроизводимых действий проекта без дублирования подробной документации.
Проверка¶
- проверка наличия корневого
README.mdи перечисленных сведений; - автоматическая проверка локальных ссылок из чистого checkout;
- сопоставление перечня компонентов с manifest и поставляемыми артефактами;
- выполнение указанных команд либо команд по связанным документам.
Исключения¶
Не допускаются для имени и расположения корневой точки входа. Отклонение от
локального сценария запускаемого приложения регулируется DEV-RUN-004.
DEV-DOC-002. Актуализация вместе с изменением¶
Уровень: MUST
Применяется к: изменению назначения проекта, ответственности или состава компонентов, публичного контракта, поддерживаемого запуска либо обязательной проверки
Merge request должен обновлять в том же diff каждый версионируемый документ,
утверждение которого без обновления станет ложным или неполным. Корневой
README.md должен обновляться при изменении любого из сведений, обязательных
по DEV-DOC-001. Неизменившаяся ссылка на актуализированный документ не
требует отдельного изменения README.md.
Описание merge request должно перечислять обновлённые документы либо указывать, что документация не затронута, и называть утверждение или машинный источник, по которому это определено.
Применимые обязательные проверки документации по DEV-DOC-001 и
DEV-DOC-003 должны блокировать merge по правилам DEV-VER-003.
Обоснование¶
Отдельная от реализации актуализация оставляет в основной ветке период, когда точка входа или контракт описывают уже несуществующее поведение.
Проверка¶
- сопоставление diff поведения, контрактов, manifest и документации;
- проверка заявленного влияния на документацию в merge request;
- контролируемое изменение документированного свойства без изменения соответствующей документации;
- проверка блокировки merge при неуспешном documentation job.
Исключения¶
Экстренное изменение по OPS-INC-003 MAY актуализировать документацию после
стабилизации, если issue последующего действия содержит владельца и срок.
DEV-DOC-003. Воспроизводимая машинно-производимая документация¶
Уровень: MUST
Применяется к: машинно-производимой справочной документации проекта
Проект должен формировать машинно-производимую справочную документацию из определяющего её источника. Проект должен объявить этот источник истины, неинтерактивную команду формирования, зафиксированные версии генератора и расположение результата. Сформированный результат не должен редактироваться как независимый источник контракта.
Обязательный CI job должен формировать документацию из чистого checkout проверяемого commit. Если результат хранится в Git, job должен завершаться ошибкой при любом diff после повторного формирования. Если результат публикуется только как артефакт, job должен публиковать результат того же commit и сохранять его commit SHA в metadata артефакта.
Обоснование¶
Воспроизводимое формирование устраняет ручное расхождение между машинным контрактом и его точным справочным представлением для потребителя.
Проверка¶
- повторный запуск объявленной команды в чистом checkout;
- контролируемое изменение источника без обновления committed-результата;
- сопоставление версии генератора и commit SHA опубликованного артефакта;
- проверка блокировки merge при ошибке, timeout или diff генерации.
Исключения¶
Авторский текст, частичный пример и описание назначения, причин решения или ограничений MAY сопровождаться вручную, если они не задают полный перечень, определённый термином этого документа. Ручное сопровождение такого полного перечня требует ADR с технической причиной отсутствия генератора, владельцем и сроком пересмотра.