Calendar Favorite 1 Streamline Icon:  Mark Your Calendars: The next VSecM Contributor Sync will be on... Thursday, 2024-05-30 at 8:00a Pacific time.
Rating Star 1 Streamline Icon:  Star VMware Secrets Manager to show your support. Help us reach out to even more people with this amazing tech.

ADR-0002: Use Markdown for Architectural Decision Records

  • Status: accepted
  • Date: 2024-05-08
  • Tags: doc

Link Context and Problem Statement

We want to record architectural decisions made in this project. Which format and structure should these records follow?

Link Considered Options

Link Decision Outcome

Chosen option: “MADR 2.1.2 with Log4brains patch”, because

  • Implicit assumptions should be made explicit. Design documentation is important to enable people understanding the decisions later on. See also A rational design process: How and why to fake it.
  • The MADR format is lean and fits our development style.
  • The MADR structure is comprehensible and facilitates usage & maintenance.
  • The MADR project is vivid.
  • Version 2.1.2 is the latest one available when starting to document ADRs.
  • The Log4brains patch adds more features, like tags.

The “Log4brains patch” performs the following modifications to the original template:

  • Change the ADR filenames format (NNN-adr-name becomes YYYYMMDD-adr-name), to avoid conflicts during Git merges.
  • Add a draft status, to enable collaborative writing.
  • Add a Tags field.



Link ADRs

You can view the ADRs by browsing this following list:

edit this page ✏️