Principal Engineering
Uniformity. Consistency. Reproducibility.

adr-tools

Многие команды для обсуждения и ведения ADR используют инструменты, подобные Confluence и Wiki. Все мы прекрасно понимаем, что это подход “write once, read never”.

В своей команде я сразу принял решение вести ADR внутри сквозной технической документации проекта, используя adr-tools. Это даёт нам:

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

Создание, ревью и замещение ADR проходят тот же самый путь через Merge Request, что и код. При просмотре MR легко предлагать правки или прикладывать патчи, которые можно применять сразу же.

Версия adr-tools зафиксирована в корне репозитория с документацией в файле .tool-versions утилиты asdf. Это даёт гарантию, что мои коллеги будут использовать строго определенную версию инструмента:

cat .tool-versions
adr-tools 3.0.0

adr-tools имеет очень простой интерфейс командной строки:

  • adr init [path] — инициализация каталога ADR. Рекомендую выполнять эту команду в корне репозитория с документацией, в качестве пути указать отдельную папку для ADR. Команда создаёт в текущей директории файл .adr-dir, указывающий на только что созданную папку. Это сильно упрощает дальнейшее использование команды adr прямо из корня репозитория.
  • adr new Use linters for code — создаёт новую запись в формате .md по шаблону, предложенному Michael Nygard, с заголовком, переданным в качестве аргумента.
  • adr new -s NUMBER Stop using linters for code — создаёт новую ADR, замещающую старую с номером, переданным в качестве аргумента.

Опыт применения adr-tools показывает, что это, возможно, единственный надёжный и переносимый инструмент для ведения ADR. Шаблон, предложенный Michael Nygard является лучшим, если не единственным, среди альтернатив.

Ссылки