Consider Architectural Decision Records (ADR)

[rainij]

See e.g. adr.github.io. During the kickoff meeting the architecture group proposed the use of ADR. They mentioned arc42 as one concrete methodology.

Inform about it and decide if we want to do this and what the format should be. Example: A possible implementation would be a flat list of files under /docs/adr/, e.g. 0004-use-mlir.md.

Possible ADR headlines are:

• Use MLIR to implement the core compiler.
• Use QDMI to query device info.
• Use ADRs! (should be the first ADR)

As a first step we decided to create a PR with a markdown template. See also #2 (comment) .

[rainij]

@schweikart any input on this?

[schweikart]

Keeping a record of architectural decisions is an excellent idea! ADRs are in fact also one pillar of the arc42 architecture documentation framework, so that will work well together. We will soon create a repository containing this architectural documentation. The only thing I'm not quite sure about yet is how we avoid having two different sources for architectural decisions while ensuring that you guys can maintain your ADRs without unnecessary overhead. Maybe we can distinguish between architectural decisions only relevant to the internals of the compiler and those that affect the overall architecture? There might not be a clean cut though... Let me raise this with the reference architecture team, I'll get back to you next week!

[burgholzer]

In principle, I am in favor of this.
We should just be careful to not overburden us with formal processes that slow down momentum.
If we agree that not every single detail, but only major decision factors, need an ADR, I believe this is a good idea.

[rainij]

Totally agree on what was said so far.

It should be low overhead. From what I read architectural decisions should be "important" things in the sense of "If I change it later it will be incredibly expensive". The usage of MLIR is such an example. Not many decisions will qualify for this so the amount of ADRs should be low.

Keep it simple. I think if we have a template of some sorts (one paragraph for the decision, up to a page for the rationale) this might also help.

I also believe that there will be some overlap with the architecture group. But I could imagine that you use another format and concentrate more on the big picture.

It might make sense to coordinate this a bit. I will reach out internally.

[schweikart]

We had a meeting today to discuss adopting ADRs into the repository. Here's a recap of my presentation (slides are in the internal Nextcloud):

• Software architecture involves complex decisions driven mainly by qualitative requirements (eg performance or an evolving environment). These requirements and circumstances can change over time but re-assessing the decision is difficult if decisions were not documented properly.
• Architectural Decision Records (ADR) aim to document the context, outcome and consequences of architecturally relevant decisions.
• Markdown Architectural Decision Records (MADR) are a possible format for documenting ADRs. MADRs are usually stored in a docs/adr folder inside the repo and use a simple markdown-based template structure.
• Architectural Documentation such as ADRs help preserving architectural knowledge and establishing a common understanding but cost and benefit must be carefully balanced to ensure usefulness.
  • Low overhead can be attained by limiting ADRs to architecturally significant (ie wide-ranging, hard to correct and controversial) decisions
  • MADRs also reduce overhead by keeping ADRs close to the code and editable with arbitrary IDEs

In the discussion after the talk we agreed that it would be helpful to adopt ADRs for major decisions in the compiler project:

• Fundamental decisions in an innovative project like this compiler should be documented to help deal with the complexity
  • @ystade reported that having a rationale document helped keep a good overview in QDMI
• Documentation overhead should be kept at a minimum so this should really only cover fundamental decisions
  • Maintainers will keep track of documenting such decisions
  • There should not be too many of these decisions (inspecting large repositories reveals that the number of MADRs in a project rarely exceeds a few dozen)

As everyone present at the meeting was in favour of adopting ADRs, @rainij suggested to leave some further room for discussion in this issue before adding the template and some first ADRs (such as choosing MLIR) to the repo. In a corresponding PR, we would also need to discuss which template to use (the full MADR template is a bit lengthy, the reduced template is very minimal, one could also opt to choose something in between).

[EnriqueNB]

The corresponding initial PR should contain the reduced template and we can discuss what to add from there. I am in favour of this but we should keep it minimal to not add much overhead.

[ystade]

In my opinion, the reduced one is slightly too minimal as already was pointed out. I would add some metadata, like the main decision makers in the template.

[rainij]

@schweikart would you like to do the PR on the template? If yes please assign yourself to this issue.