Skip to content
Snippets Groups Projects
Select Git revision
  • max/type-system-rs
  • kbezuglyi/update_rust_to_latest
  • dixitix/ignore-alien-messages
  • eivkov/alter-table
  • dixitix/governor-randomize-testing
  • kbezuglyi/deprecation_rpc_pgproto
  • max/remove-unnecessary-sbroad-error-traits
  • kbezuglyi/governor_upgrade_script
  • kusancho/february25/parametrize_cache
  • kbezuglyi/enable_backwards_compatibility_tests
  • master default protected
  • vbabayan/1430-minimal-metrics-enchancement
  • ekhamitov/751-values-hash-v5
  • vbabayan/1086-lua-mode-still-requires-delimiter
  • sql-scalar-functions
  • ekhamitov/751-values-hash-v6
  • astrochuk/remove-lua-tests
  • afetisov/better-errors
  • gmoshkin/remove-config-parameter-option
  • gmoshkin/migration-lock-already-acquired
  • 25.1.1 protected
  • 25.2.0 protected
  • 1.7.4 protected
  • 24.6.1 protected
  • 24.7.0 protected
  • 24.6.1-rc1 protected
  • 24.3.4 protected
  • 24.5.1 protected
  • 24.6.0 protected
  • b-uroboros-supply-v1 protected
  • 24.3.3 protected
  • 24.4.1 protected
  • 24.5.0 protected
  • 24.3.2 protected
  • 24.2.4 protected
  • 24.2.3 protected
  • 24.4.0 protected
  • 24.3.1 protected
  • 24.2.2 protected
  • 24.2.1 protected
40 results
Blame Permalink
README.md 3.82 KiB

ADR Process

Overview

An architectural decision record (ADR) is a document that describes a choice the team makes about a significant aspect of the software architecture they’re planning to build.

The ADR process outputs a collection of architectural decision records. This collection creates the decision log. The decision log provides the project context as well as detailed implementation and design information.

Project members skim the headlines of each ADR to get an overview of the project context. They read the ADRs to dive deep into project implementations and design choices. When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR.

When ADR is needed

In our context usually an ADR is based on functional requirements represented as an epic. Some signs that you might need an ADR:

  1. Implementing a new major feature
  2. Huge refactoring in codebase
  3. The solution can not be expressed in a couple of sentences in an issue
  4. The solution has several alternatives that need to be considered
  5. The decision in previous ADR needs to be reconsidered

How to propose an Architectural Decision

Make a copy of adr-template in this directory. Rename it to {creation-date}-{adr-title}.md (e.g. 01-01-2024-plugins.md). We use the date so it's possible to sort them correctly by file name.

Fill the sections that you find relevant for the discussion. Feel free to add additional sections if needed. The template is not strict. You can use any ADR structure that feels best for a particular case. See these ADR examples for inspiration:

Both Russian and English languages are allowed for ADRs.

Open a merge request to this repository and start the ADR discussion in the comments. The suggested prefix for the commit and MR name is adr:.

Google Docs

Alternatively if you prefer Google Docs, you can open an empty MR with a link to ADR Google Doc where the discussion will happen. Though it will be still needed to fill the ADR here and merge the MR for ADR to be accepted.

What happens next?

Then as the owner of an ADR and a merge request it's your task to drive it to completion. Get comments from the relevant stakeholders, set deadlines and schedule ADR review meetings as suggested by AWS Guidlines.

ADR - Accepted

ADR is accepted when the merge request is approved by the relevant stakeholders. Then the status in the template is set to accepted and the MR is merged. So every ADR that this repository contains should be a final decision with no unanswered questions.

ADR - Rejected

If the suggested change is rejected it is also important to merge the ADR, with the rejected status and rationale of the rejection.

ADR - Superseded

When there is a need to make an update on the decision that was previously taken. Instead of updating an old ADR, one should make an alternative ADR with a reference to the previous one on this topic. When such an MR is approved, the previous ADR's status is changed to superseded by ....

Useful Links