Skip to content

Introduce ADRs for the project #365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
andregasser wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Introduce ADRs for the project #365

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c74b4f7
Introduce ADRs for the project
Nov 29, 2023
403aa1d
Move ADR for exception handling into separate PR
Nov 29, 2023
f3941e2
Refine ADR process and template
Jan 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions adr/adr-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# ADR Process

## Overview

In the BigBone project, we use ADRs to log the outcome of design and decision making activities. Hence, we can view them
Copy link
Owner

@PattaFeuFeu PattaFeuFeu Nov 29, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should write down in full what “ADR” means at least once here at the start of the document. At least I didn’t know that abbreviation.

Copy link
Collaborator Author

@andregasser andregasser Nov 29, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I had it written out somewhere but it seems it did not make it into this PR. Will fix it. 👍

as journals, akin to meeting outcome summaries or discussion notes. ADRs help future developers to better understand why
things are done in a particular way.

## Process

The process for discussing architectural or design topics is initiated by first identifying a need for discussing it.
Once the team has agreed that there is a real need for having an in-depth discussion, the process is initiated as
follows:

1. The initiator of the topic creates a new discussion thread under the "Architecture & Design" category. The topic is
discussed on the discussion thread and members agree on a decision to be taken.
2. The outcome of the discussion should be recorded in a new ADR inside the `/adr` folder. Please use the provided
template for this (`adr-template.md`). Give your ADR a meaningful name, such as `0001-exception-handling.md`. For
every future ADR, the number should be incremented by 1.
3. Also please place a link in the discussion thread that points to the newly created ADR.
4. If concrete action needs to be taken, please open issues for all of them and refer to the ADR.

## More on ADRs

- https://adr.github.io/
- https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html (best practices, anti-patterns and such)
17 changes: 17 additions & 0 deletions adr/adr-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# ADR <Four digit number>: <Title>

## Status

The status of this ADR. It can be either Proposed, Accepted, Rejected, Deprecated, Superseded.
Copy link
Collaborator

@bocops bocops Nov 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume that any existing ADR could be deprecated/superseded by the outcome of a new discussion thread but I think it is still worth explaining Deprecated and Superseded including the differences between these two, or rather the process that leads to these statuses, somewhere.

If we propose changes via a separate discussion thread and an ADR is only written after that discussion has ended, we should never have an ADR in the status Proposed.

Similarly, what is the purpose of documenting something as Rejected? If a discussion leads to something else than the originally suggested design, can't we just record this as a different design being Accepted?

Explanations for these terms should probably be added to adr-process.md as necessary.


## Context

What is the issue that we're seeing that is motivating this decision or change?

Comment on lines +12 to +15
Copy link
Collaborator

@bocops bocops Nov 29, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Context" should probably include a link to the discussion thread that led to the ADR.

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?