Opinionated Digital Center's Architecture Decision Record Repository

The Opinionated Digital Center's team has decided to use the Architecture Decision Record approach to record the reasoning behind the opinionated choices it makes (see ADR-0000).

Cross-cutting decisions are held in this repository (see table of content), whereas project specific ADRs are held in each project's docs/adr directory.

What is an Architecture Decision Record (ADR)?

To learn about ADRs, see:

• Joel Parker Henderson's page.
• The original article from Michael Nygard.

Proposing a new ADR

Please note that:

• ADR uses the MADR template.
• Only one ADR must be proposed per feature branch (one file with name starting with XXXX).

The process is as follows:

1. Create a feature branch from master:

   git switch master
   git switch -c <your-feature-branch>

2. Create a new file in docs/adr/ using the template in place:

   • The file name should follow the convention as detailed in ADR-0001 ("Positive consequences" section), with XXXX in place of its unique number (For example XXXX-use-markdown-architectural-decision-records.md).

3. Fill your ADR:

   • Status line exists and is set to proposal.
   • Date line exists and is set to current date.

4. Once finish, commit your work with message either (title follows MADR-0005-format):

   • When working on a repo dedicated to ADRs:

     git commit -m 'feat(adr): <adr-title-in-lowercase>'

   • OR when working on a project's repo:

     git commit -m 'docs(adr): <adr-title-in-lowercase>'

5. Push feature branch to Github:

   git push --set-upstream origin <your-feature-branch>

6. Create a PR.

Once the PR is created, it will be reviewed and discussed.

ADR approval/rejection process flow

Before PR merge

On the PR branch:

1. Make sure you are on the correct feature branch and rebase to master:

   git switch -c <your-feature-branch>
   git rebase master

2. Squash commits and rewrite commit message with (title follows MADR-0005-format):

   • When working on a repo dedicated to ADRs:

     git reset --soft master && git commit -m 'feat(adr): <adr-title-in-lowercase>'

   • When working on a project's repo:

     git reset --soft master && git commit -m 'docs(adr): <adr-title-in-lowercase>'

3. Update the following ADR content:

   • Change ADR status to approved or rejected.
   • Change ADR date to current date.

4. Change ADR .md file name from XXXX-<whatever-is-here> to <next-available-id>-<adr-title-in-lowercase> (follows MADR-0005-format).

5. Force push your feature branch:

   git push -f

6. merge the PR.

After PR merge

Pull merge code from GitHub and remove your feature branch:

git switch master
git pull origin
git remote prune origin
git branch -D <your-feature-branch>