ADR

Представьте, что в компании/команде где вы работаете, принимаются решения, которые изменяют архитектуру проекта, но при этом это никак не документируется. Представить такую ситуацию очень легко, потому что практически везде так и происходит. Особенно это чувствуется на онбординге новых сотрудников. Когда поступает много вопросов, например: "А почему используется mongoDB", "А почему пользователи хранятся в одной базе данных, а все остальное в другой?", "А почему..." и так далее, куча вопросов "почему", а ответов на них нет в документации, есть только те, кто уже давно работают в компании, но и не всегда они знают ответ, потому что тот, кто принимал решение, наверное уже не работает в этой компании. Все это может привести к очень плохим последствиям, если изменения, которые опять будут внесены, будут сделаны без знания исторически сложившейся архитектуры. А под плохими последствиями я имею ввиду то, что изменения могут выстрелить в каком-то уже давно забытом и автономном сервисе, или в какой-то одной функции, которая также уже давно была написана и отлично работала, опираясь на заложенную логику. Чтобы такого избежать, надо всегда документировать любые архитектурные решения и такая практика называется ADR (Architecture Decision Records) или иными словами: (Запись архитектурных решений). Есть несколько вариантов ADR. Один из самых простых, это создать single repo, в которой шаблон, вида 0000-template.md, со следующими полями: - Name: короткое именное словосочетание, содержащее архитектурное решение. - Status: Proposed | Accepted | Rejected | Superseded - Context: В этом разделе приводится краткое описание задачи, состоящее из пары предложений - Considered Alternatives: Тут приводятся альтернативные варианты - Pros and Cons of the Alternatives: Плюсы и минусы по каждому альтернативному решению - Decision Outcome: Выбранное решение с описанием причин, почему это решение было выбрано Второй вариант немного сложнее, потому что ADR директория создается в каджом репозитории проекта микросервисной архитектуры и настраивается CI/CD, который после мерджа в мастер, копирует новые записи в единый общий репозиторий. Это с одной стороны удобно, но я предпочитаю single-repo, где локализовано всё обсуждение в созданном пул реквесте. Из инструментов я использовал adr-log это npm пакет, есть и другие варианты, но этот показался достаточно простым, другие я не рассматривал. Telegram | Youtube | Twitter