Architectural Decision Record

[leclairm]

No description provided.

[DropD]

I would suggest to record each architectural decision in it's own markdown file. That way we can avoid unneccessary conflicts. This means the name and/or location has to be a bit more unique than src/sirocco/ADR.md. I can see two ways to organize this successfully:

• ADR_<topic name>.md as close to the relevant source as reasonable with the topic name potentially shorter based on the location (can be a bit tricky if there is a design change touching multiple modules). Might lead to moving ADRs around during refactorings.
• adr folder toplevel or in docs (could then be served with mkdocs for easy browsing), with a topic based naming scheme. Example: https://github.com/GridTools/gt4py/tree/main/docs/development/ADRs.

I guess the two ways could be combined by adding subfolders in an ADR folder, based on which part of the code the ADRs are relevant to.

[leclairm]

Point taken. I'd go for the second option but not in docs. I'd prefer to keep the docs user oriented and not dev.

[leclairm]

@DropD which of the following options would you advise to update the ADR documents?

• overwrite the document with the latest design so that it's easily readable. History is then only accessible in older commits.
• append / insert updates so that the history remains visible but the current design needs to be reconstituted by the reader by merging the different updates with the original document.

[leclairm]

In our meeting today we diced that we could mix the 2 update policies: add updates between stable versions and rewrite in-between. Still the current ADR about Store and Array would take a bit of time to rewrite so I leave it for later. See #112

[DropD]

in GT4Py we use something we copied from other projects like Python (PEP) or NumPy (NEP). Each of our ADRs has a header where we can state whether this is current or has been replaced by another one. Also when it has last been changed and why.

So we update ADRs with small changes, but for bigger changes we create a new one which links to the old one but shouldn't require reading the old one. The old one is then updated to say that it has been superseded by the new one. This is how we keep the history available.