memgraph/ADRs

Architecture Decision Records

Also known as ADRs. This practice has become widespread in many high performing engineering teams. It is a technique for communicating between software engineers. ADRs provide a clear and documented history of architectural choices, ensuring that everyone on the team is on the same page. This improves communication and reduces misunderstandings. The act of recording decisions encourages thoughtful consideration before making choices. This can lead to more robust and better-informed architectural decisions.

Links must be created, pointing both to and from the Github Issues and/or the Notion Program Management "Initiative" database.

ADRs are complimentary to any tech specs that get written while designing a solution. ADRs are very short and to the point, while tech specs will include diagrams and can be quite verbose.

HOWTO

Each ADR will be assigned a monotonically increasing unique numeric identifier, which will be zero-padded to 3 digits. Each ADR will be in a single markdown file containing no more than one page of text, and the filename will start with that unique identifier, followed by a camel case phrase summarizing the problem. For example: 001_architecture_decision_records.md or 002_big_integration_cap_theorem.md.

We want to use an ADR when:

1. Significant Impact: This includes choices that affect scalability, performance, or fundamental design principles.
2. Long-Term Ramifications: When a decision is expected to have long-term ramifications or is difficult to reverse.
3. Architectural Principles: ADRs are suitable for documenting decisions related to architectural principles, frameworks, or patterns that shape the system's structure.
4. Controversial Choices: When a decision is likely to be controversial or may require justification in the future.

The most senior engineer on a project will evaluate and decide whether or not an ADR is needed.

Do

1. Keep them brief and concise.
2. Explain the trade-offs.
3. Each ADR should be about one AD, not multiple ADs
4. Don't alter existing information in an ADR. Instead, amend the ADR by adding new information, or supersede the ADR by creating a new ADR.
5. Explain your organization's situation and business priorities.
6. Include rationale and considerations based on social and skills makeups of your teams.
7. Include pros and cons that are relevant, and describe them in terms that align with your needs and goals.
8. Explain what follows from making the decision. This can include the effects, outcomes, outputs, follow ups, and more.

Don't

1. Try to guess what the executive leader wants, and then attempt to please them. Be objective.
2. Try to solve everything all at once. A pretty good solution now is MUCH BETTER than a perfect solution later. Carpe diem!
3. Hide any doubts or unanswered questions.
4. Make it a sales pitch. Everything has upsides and downsides - be authentic and honest about them.
5. Perform merely a superficial investigation. If an ADR doesn't call for some deep thinking, then it probably shouldn't exist.
6. Ignore the long-term costs such as performance, tech debt or hardware and maintenance.
7. Get tunnel vision where creative or surprising approaches are not explored.

Template - use the format below for each new ADR

1. Author - who has written the ADR
2. Status - one of: PROPOSED, ACCEPTED, REJECTED, SUPERSEDED-BY or DEPRECATED
3. Date - when the status was most recently updated
4. Problem - a concise paragraph explaining the context
5. Criteria - a list of the two or three metrics by which the solution was evaluated, and their relative weights (importance)
6. Decision - what was chosen as the way forward, and what the consequences are of the decision