You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Current »

Approved by consent of the TSC 11/19/21

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.

EdgeX has two places to record design decisions.

  1. Any and all design/architectural decisions regardless of size or impact shall be captured on the EdgeX Foundry Design Decisions project board.
  2. 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.

When to use an ADR

“Significant architectural decisions” are deemed those that:

  • Impact more than one EdgeX service and often impact the entire system (such as the definition of a data transfer object used through the system, of a feature that must be supported by all services).
  • Require a lot of manpower (more than two people working over the course of a release or more) to implement the feature outlined in the ADR.
  • Requires implementation to be accomplished over multiple releases (either due to the complexity of the feature or dependencies).

Project Board Cards and Issues

All project design/architectural design decisions captured on the Design Decisions project board will be created as either a:

  • 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).

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.

The release columns may be “frozen” at the end of a release, but should never be deleted so that all design decisions can be retained for the life of the project.

Ownership and Card/Issue Creation

The TSC chair, vice-chair and product manager will have overall responsibility for the Design Decision project board.  These people will also be responsible for capturing any decisions from TSC meetings or the Monthly Architect’s Meeting as cards/issues on the board.

Work Group chairs are responsible for adding new design decision cards/issues that come for their work group or related meetings.


  • No labels