Processo de ADR

Um registro de decisão arquitetônica (ADR) é um documento que descreve uma escolha que a equipe faz sobre um aspecto significativo da arquitetura de software que eles planejam criar. Cada ADR descreve a decisão arquitetônica, seu contexto e suas consequências. Os ADRs têm estados e, portanto, seguem um ciclo de vida. Para obter um exemplo de ADR, consulte o apêndice.

O processo de ADR gera uma coleção de registros de decisão arquitetônica. Essa coleção cria o log de decisões. O log de decisões fornece o contexto do projeto, bem como informações detalhadas de implementação e design. Os membros do projeto percorrem as manchetes de cada ADR para obter uma visão geral do contexto do projeto. Eles leem os ADRs para se aprofundar nas implementações do projeto e nas opções de design.

Quando a equipe aceita um ADR, ele se torna imutável. Se novos insights exigirem uma decisão diferente, a equipe proporá um novo ADR. Quando a equipe aceita o novo ADR, ele substitui o ADR anterior.

Escopo do processo de ADR

Os membros do projeto devem criar um ADR para cada decisão arquitetonicamente significativa que afete o projeto ou produto de software, incluindo o seguinte (Richards e Ford 2020):

• Estrutura (por exemplo, padrões como microsserviços)

• Requisitos não funcionais (segurança, alta disponibilidade e tolerância a falhas)

• Dependências (acoplamento de componentes)

• Interfaces (APIs e contratos publicados)

• Técnicas de construção (bibliotecas, estruturas, ferramentas e processos)

Requisitos funcionais e não funcionais são as entradas mais comuns para o processo de ADR.

Conteúdo do ADR

Quando a equipe identifica a necessidade de um ADR, um membro da equipe começa a escrever o ADR com base em um modelo para todo o projeto. (Consulte Organização do ADR GitHub para obter modelos de exemplo.) O modelo simplifica a criação de ADR e garante que o ADR capture todas as informações relevantes. No mínimo, cada ADR deve definir o contexto da decisão, a decisão em si e as consequências da decisão para o projeto e seus resultados. (Para obter exemplos dessas seções, consulte o apêndice.) Um dos aspectos mais poderosos da estrutura do ADR é que ela se concentra no motivo da decisão e não em como a equipe a implementou. Entender por que a equipe tomou a decisão facilita que outros membros da equipe adotem a decisão e impede que outros arquitetos que não estavam envolvidos no processo de tomada de decisão anulem essa decisão no futuro.

Processo de adoção do ADR

Cada membro da equipe pode criar um ADR, mas a equipe deve estabelecer uma definição de propriedade para um ADR. Cada autor proprietário de um ADR deve manter e comunicar ativamente o conteúdo do ADR. Para esclarecer essa propriedade, este guia se refere aos autores de ADR como Proprietários de ADR nas seções a seguir. Outros membros da equipe sempre podem contribuir para um ADR. Se o conteúdo de um ADR mudar antes que a equipe aceite o ADR, o proprietário deverá aprovar essas alterações.

O diagrama a seguir ilustra o processo de criação, propriedade e adoção do ADR.

Depois que a equipe identifica uma decisão arquitetônica e seu proprietário, o proprietário do ADR fornece o ADR no estado Proposto no início do processo. ADRs no estado Proposto estão prontos para revisão.

O proprietário do ADR então inicia o processo de revisão do ADR. O objetivo do processo de revisão do ADR é decidir se a equipe aceita o ADR, determina que ele precisa ser retrabalhado ou rejeita o ADR. A equipe do projeto, incluindo o proprietário, revisa o ADR. A reunião de revisão deve começar com um horário dedicado para ler o ADR. Em média, 10 a 15 minutos devem ser suficientes. Durante esse período, cada membro da equipe lê o documento e adiciona comentários e perguntas para sinalizar tópicos pouco claros. Após a fase de revisão, o proprietário do ADR lê e discute cada comentário com a equipe.

Se a equipe encontrar pontos de ação para melhorar o ADR, o estado do ADR permanecerá Proposto. O proprietário do ADR formula as ações e, em colaboração com a equipe, adiciona um responsável para cada ação. Cada membro da equipe pode contribuir e resolver os pontos de ação. É responsabilidade do proprietário do ADR reprogramar o processo de revisão.

A equipe também pode decidir rejeitar o ADR. Nesse caso, o proprietário do ADR acrescenta um motivo para a rejeição para evitar futuras discussões sobre o mesmo tópico. O proprietário altera o estado do ADR para Rejeitado.

Se a equipe aprovar o ADR, o proprietário adicionará um registro de data e hora, uma versão e uma lista de partes interessadas. O proprietário então atualiza o estado para Aceito.

Os ADRs e o log de decisões que eles criam representam as decisões tomadas pela equipe e fornecem um histórico de todas as decisões. A equipe usa os ADRs como referência durante as revisões de código e arquitetura, sempre que possível. Além de realizar revisões de código, tarefas de design e tarefas de implementação, os membros da equipe devem consultar os ADRs para tomar decisões estratégicas para o produto.

O diagrama a seguir mostra o processo de aplicação de um ADR para validar se uma alteração em um componente de software está em conformidade com as decisões acordadas.

Como boa prática, cada mudança de software deve passar por revisão por pares e exigir pelo menos uma aprovação. Durante a revisão do código, um revisor de código pode encontrar alterações que violem um ou mais ADRs. Nesse caso, o revisor solicita que o autor da alteração do código atualize o código e compartilhe um link para o ADR. Quando o autor atualiza o código, ele é aprovado por revisores pares e incorporado à base de código principal.

Processo de revisão de ADR

A equipe deve tratar os ADRs como documentos imutáveis depois de aceitá-los ou rejeitá-los. Mudanças em um ADR existente exigem a criação de um novo ADR, o estabelecimento de um processo de revisão para o novo ADR e a aprovação do ADR. Se a equipe aprovar o novo ADR, o proprietário deverá alterar o estado do ADR antigo para Substituído. O diagrama a seguir ilustra o processo e atualização.