INFO

This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository. You can find the original version here

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.

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.