NEXT-20194 - Added guideline for writing ADRs

coding-guidelines/core/adr.md

@@ -0,0 +1,29 @@
+# ADR
+
+This guideline describes what we expect from our ADRs and how you can write some.
+
+Joel Parker Henderson has done a lot of work on this topic, collected excellent ideas, tips, templates, and examples, and published them on [github](https://github.com/joelparkerhenderson/architecture-decision-record).
+
+The ADRs examples published there are good.
+
+Expectations for an ADR:
+- Write a complete description of the requirements
+- List all technical domains that are affected by the ADR
+- List all affected logic in the system that are affected
+- Write some pseudo code for your new logic to visualize what you want to realize
+- Define all public APIs that are to be created or changed with your new logic
+- Define how developers can extend the new APIs and logic and what possible business cases you see
+- Define the reason why you made the decision. It often helps to understand why you made a specific architectural change in the future.
+- Define all consequences of the decision and how they impact a developer who has used the code/product.
+
+Everyone takes a different approach to create ADRs and meeting the expectations above. One possible approach is the following:
+
+- Create a list of domains you want to touch (Store-API, admin process, indexing, ...)
+- Create a headline for each domain
+- Describe the domains. After each headline, write in 2 sentences why this domain is relevant for this ADR
+- Describe the "problems" of each domain... write in each domain which logic has to be touched... not how you want to change them, only why
+  - e.G. indexing: "We have to extend the product indexing process because calculating the new product data is too expensive, and we want to calculate the values in a background job."
+- Describe the "solution" of each domain... write in each domain how you want to extend the above logic to solve your "problems."
+- Add a new section about extendability and write down how developers should be able to extend your system and which business cases you see
+- Last, add some pseudocode at the end to visualize your solutions and ideas.
+