Skip to content

2020-08-10 - Architecture decision records


We document architecture and technical decisions for HEPTAconnect. Inspired by we follow the same principles and use ADRs to keep track of decision making to make it easier to understand why things are how they are:


Having the ADRs as part of the versioning adds more pros:

  • Decisions remain in sync with the code itself
  • The Git history is also the decision history
  • Decisions are public available and accessible for every developer
  • Also external developers can add new ADRs via GitHub pull requests


Every architectural change or addition should contain a Markdown file like this to have a brief understanding what are the pros, cons and how it should be used. Until the release of version 1.0.0 it is ok to add ADRs for decisions made in the past. This is the reason why you probably find ADRs with a timestamp before we decided to add ADRs.

ADRs have to approved by a maintainer when they are proposed by a contributor. As a past ADR can't be changed it has to be marked as deprecated by copying it into the deprecated folder, change the original file to link to the copy and refer to the new superseeding ADR.

How does an ADR look like?

You can use this first ADR as an orientation. The filename of the ADR should contain the date and a meaningful title. The content of the ADR should always use the following template:

# [Date] - [Title]
## Context
## Decision
## Consequences
### Pros
### Cons
### How to use
## Related thoughts