Skip to content



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


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.