study ADR (architectural decision records) and consider schematics for it

[nongrata081]

Justification

• Michael Nygard: Documenting Architecture Decisions
• Uwe Zdun: Sustainable architectural decisions

Types of ADRs (templates):

• ADR template by Michael Nygard (simple and popular)
• ADR template by Jeff Tyree and Art Akerman (more sophisticated)
• ADR template for Alexandrian pattern (simple with context specifics)
• ADR template for business case (more MBA-oriented, with costs, SWOT, and more opinions)
• ADR template MADR (more Markdown)
• ADR template using Planguage (more quality assurance oriented)
• MADR - Markdown Architectural Decision Records

Resources

• ADR examples & knowledge base
• Github ADR organization
• Homepage of the ADR GitHub organization

Tooling

• adr-tools - bash scripts to manage ADRs in the Nygard format
• npm adr package - npm package

[nongrata081]

• [ ] study AKM (Architecture Knowledge Management): https://www.ifs.hsr.ch/index.php?id=13201&L=4

[nongrata081]

• [ ] Analyze & consider implementing ADRs in the code itself, analogous to embedded JAVA ADRs (could be implemented as TS decorators, but what for? what benefit does it give? what about other files - sass, bash, etc? will we write a parser for each of these? or write a universal one that would recognize it?)
• [ ] Analyze & consider implementing ADRs as generated from conventional commit history, from a separate conventional commit type 'architecture' (would have to handle a situation when a single ADR spans across multiple commits, and has to be referenced in all of them).
  • [ ] The generated ADR-log can then be converted to an html file, that would have a front-end with some functionality, like grouping ADRs by a group on some criteria (context), or filtering those by a tag, etc. (the FE for that would be pre-built as a template).
  • [ ] Analyze how to handle a case when for one commit there are multiple ADRs (e.g. scaffolding @nrwl/nx monorepo)
  • [ ] Analyze in which way to handle a situation of retrospective conventional commit history change in case if a new ADR supercedes an old one. In that case new ADR should state it Supercedes <%># N ADR<%> and the superceded one should also be updated to have the same line Superceded by <%># X ADR<%>. Can we do it with the commit history? Do tags allow that?
  • [ ] Is it possible to support all adr scripts that original bash script provides with commit history? (link, generate, list, config, new, upgrade-repository)
  • [ ] How to handle a situation when some ADRs are pending, and exist just as proposals that are being considered, but for which there is no action yet ? new, link, list, config, generate, upgrade-repository ?
  • [ ] Is it possible to handle a situation when a new ADR is created but not approved yet, and is pending for a while (spanning multiple releases) ?

[nongrata081]

• [x] Generate ADRs and ADR-log with standard Michael Nygard's template (adr-log is redundant, use adr generate toc instead)
• [ ] Generate ADRs and ADR-log with MADR template
• [ ] Compare both & analyze which is better and why

[nongrata081]

• [ ] Generate ADRs with npm adr and MADR (other templates?), is it better to the regular ADR ? In what way? (brew as opposed to npm - with npm adr is a dependency within the project codebase itself, which means it can be automated with devkit, with brew not sure how to do it)

[nongrata081]

• [ ] Compare ADR templates and analyze all their fields. What is good to have? Why? What is not? Why? Olaf Zimmermann article with comparison

[nongrata081]

• [ ] study https://adr.github.io/ all links for anything useful I didn't know yet