** Draft ** for consideration by the TSCApproved by consent of the TSC 11/19/21
| Table of Contents |
|---|
In any software system, design decisions are made on a regular, if not daily, basis. Some of these decisions are big and impactful to all parts of the system. Other decisions are less significant but still important for everyone to know and understand.
...
- Any and all design/architectural decisions regardless of size or impact shall be captured on the EdgeX Foundry Design Decisions project board.
- Significant architectural decisions should be documented in an architectural design record (ADR). ADRs must be reviewed and approved per the process outlined in the documentation on ADRs.
Note: ADRs should also be documented on the project board with a link to the ADR in edgex-docs in the project board card.
When to use an ADR
“Significant architectural decisions” are deemed those that:
...
- Issue: for any design decision that will require code and a PR will be submitted against the issue.
- Card: for any design decision that is not itself going to result in code or may need to be broken down into multiple issues (which can be referenced on the card).
The template for project board cards documenting each decision is:
- When/Where: date of the decision and place where the decision was made (such as TSC meeting, working group meeting, etc.). This section is required.
- Decision Summary: quick write-up on the decision. This section is required.
- Notes/Considerations: any alternatives discussed, any impacts to other decisions or considerations to be considered in the future (what would negate the decision). This is section optional.
- Relevant links: link to the meeting recording (if available). Link to ADR if relevant. Link to PRs or Issues if relevant. Required if available.
Note there is a Template column on the project board with a single card that specifies this same structure.
Project Board Columns
The Design Decisions project board will be permanent and never archived or deleted. For each release, a new column named for that release will be created to hold the decisions (in the form of cards or issues) for that release.
...