Источники, связи и история
Как избежать противоречий
Основной источник (источник истины) — место, сведения из которого проект считает определяющими для конкретного вида информации.
Если информация представлена в нескольких местах, проект должен явно определить основной источник или правило выбора между источниками. Например:
| Вид информации | Возможный основной источник |
|---|---|
| Состояние задач | Трекер задач |
| Принятые архитектурные решения | Реестр ADR |
| Проектные соглашения | Соответствующие документы в FISS/knowledge/ |
| История изменений файлов | Система контроля версий |
Это пример распределения ответственности, а не установленная FISS иерархия. Правила проекта следует размещать там, где их найдут при работе с соответствующим контекстом; общие правила можно включить в FISS/BOOTSTRAP.md.
В соответствии с принципом «Сохраняйте ясность основных источников», FISS не должен без необходимости дублировать код, документацию или внешние системы: копии, пересказы и проекции не должны незаметно становиться конкурирующими источниками истины. Если пересказ полезен, например как схема для человека, следует указать основной источник.
При противоречии нельзя молча выбрать удобную версию. Нужно применить явно установленное правило приоритета. Если такого правила нет, выбор источника требует отдельного решения команды.
Как связывать материалы
Связи выражаются обычными Markdown-ссылками и коротким пояснением. Отдельный язык отношений не требуется.
Например, из FISS/state/adr/payment-decision.md:
Это решение закрывает [вопрос о модели оплаты](../../state/open-questions/payment-model.md).Условие «Читать…» обязательно для навигационных ссылок в индексах. В содержательных документах достаточно пояснения самой связи.
Когда нужна история внутри документа
История изменений не обязательна в каждом артефакте. Для файлов под контролем Git техническая история уже доступна в репозитории; проект может использовать и другую систему контроля версий.
Статус или пояснение изменения полезны, когда без них можно неправильно применить материал. Например, для решения можно указать, что оно актуально, заменено другим или отменено, и дать ссылку на новое решение. Такие обозначения и необходимость отдельной истории определяет команда.