Start using ADR (Architectural Decision Records)

[fmvilas]

Problem

What's the story exposing the problem the users are facing

We'll have to make a lot of architectural decisions during the development of Studio. It would be cool to get a record of each of these decisions in a centralized place in this repo, so others can understand why we took some decisions in the past and also it would force us to not only think about the "what"s but also the "why"s of our decisions. This would prevent us from jumping straight to the latest cool technology without properly evaluating it before.

Solution

Proposed solution with mockups, views...

I'm proposing we adopt ADR (Architectural Decision Records). Learn more about it here: https://betterprogramming.pub/the-ultimate-guide-to-architectural-decision-records-6d74fd3850ee.

Since the lifecycle of an ADR can change and there should be a way for people to discuss them before they're adopted, my proposal is that we keep them in Markdown format in a folder of this repo. Every time we want to add or change an ADR, we'll have to create a pull request and there we will be able to discuss the change via GitHub comments.

These pull requests should have a specific label (e.g., kind/adr) and their title should start with [ADR-0001] to easily identify which ADR is the PR about. A PR must not change multiple ADRs.

Lastly, given the label, title, and all the information about the PR, an automated script should take care of making sure we create valid ADR PRs.

Things to validate with the automation:

1. If a PR has the kind/adr label, its title has to start with [ADR-xxxx].
2. If a PR title starts with [ADR-xxxx], we should add the kind/adr label.
3. Once 1 and 2 are met, if a PR is changing multiple files, merge should be blocked.
4. Once 1 and 2 are met, if a PR is changing the file of another ADR, merge should be blocked.

Rabbit holes

Potential technical, design ... challenges

We already have automation enforcing a specific syntax for PR titles, i.e., chore: , fix: , feat: , etc. Not sure if we can skip this enforcement or if it would be easy.

My advice is, if that takes too long to change, then let's change the signature of the PR title to chore: [ADR-xxxx] or something like that. It's not beautiful but works.

Scope

Describe a list of tasks or issues that needs to be done ( you don't need to have an exhaustive list of all the tasks in the beginning)

• Create a Markdown template for the ADR #676
• Create a GitHub action to automate ADRs validation #677
• Add some initial ADRs #678
• Demo Issue (test only) #694
• DEMO - ADR #705

Out of bounds

What won't be part of the scope

Do not try to come up with a UI to visualize the ADRs or anything like that. It's good enough to have them in a folder in Markdown format.

Success criteria

How do we know we made a good bet

The ADRs can serve as a way to onboard people to the project and for us to remember why we took some decisions.

[Amzani]

@fmvilas is rendering the ADRs part of the scope of this Bet ? we could have something similar to https://github.com/adr/adr-log/blob/main/docs/index.md and link it in the README.

[fmvilas]

Out of bounds

What won't be part of the scope

Do not try to come up with a UI to visualize the ADRs or anything like that. It's good enough to have them in a folder in Markdown format.

😄 Go ahead if you want to include it but I'd do it as a last thing.