First draft of 0001-organization-of-ADR #1
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| # Initial plan for organization of ADR files | ||
|
|
||
| * Status: proposed | ||
| * Deciders: @ZavenArra {list everyone involved in the decision using github handle} <!-- optional --> | ||
| * Date: 2022-05-11 {YYYY-MM-DD when the decision was last updated} <!-- optional --> | ||
|
|
||
|
|
||
| ## Context and Problem Statement | ||
|
|
||
| We have many decisions to make when building the treetracker platform, and we will use Architectural Decision Records (ADRs) to make more and more of these decisions. (https://adr.github.io/madr/) ADRs could be organized in a few different ways - should all decisions to be tracked in one central ADR repository, or should they be split up by teams or project areas? ADRs are assumed to be stored in a github repository or several repositories. | ||
|
|
||
| ## Decision Drivers <!-- optional --> | ||
|
|
||
| * Ease of locating ADRs for developers | ||
| * Ease of finding ADRs relevant to a particular microservice, cloud service, or project focus | ||
| * Clarity of where to create a new ADR for a particular microservice, cloud service, or project focus | ||
|
|
||
| ## Considered Options | ||
|
|
||
| * Place all ADRs in one repository, organization-wide. | ||
| * Create ADR respositories for aggregate project areas - cloud, frontend, and backend. | ||
| * Create a decisions folder within each repository, to hold only decisions relevant for that repository. | ||
| * … <!-- numbers of options can vary --> | ||
|
|
||
| <!-- | ||
| ## Decision Outcome | ||
|
|
||
| Chosen option: "{option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. | ||
|
|
||
| ### Positive Consequences <!-- optional --> | ||
|
|
||
| * {e.g., improvement of quality attribute satisfaction, follow-up decisions required, …} | ||
| * … | ||
|
|
||
| ### Negative Consequences <!-- optional --> | ||
|
|
||
| * {e.g., compromising quality attribute, follow-up decisions required, …} | ||
| * … | ||
| --> | ||
|
|
||
| ## Pros and Cons of the Options | ||
|
|
||
| ### Place all ADRs in one repository, organization-wide | ||
|
|
||
| This is the initial status quo. https://github.com/Greenstand/treetracker-decisions | ||
|
|
||
| * Good, because all ADRs reside in one location and are easy to find | ||
| * Good, because we can revisit this decision later and split off separate ADR repositories as needed | ||
| * Bad, because ADRs tracking decisions of various scope, large and small, global and very specific, are combined together and thus difficult to search. | ||
|
There was a problem hiding this comment. Perhaps we can tag each ADR with the repositories or project areas affected. |
||
|
|
||
| ### Create ADR respositories for aggregate project areas - cloud, frontend, and backend | ||
|
|
||
| * Good, because ADRs are separated by areas of concern | ||
| * Bad, because combining all frontend, or all backend, ADRs is only a marginal improvement in findability | ||
| * Bad, because some decisions will span cloud, frontend, and backend, making a fourth global ADR repo still necessary | ||
|
|
||
| ### Create a decisions folder within each repository, to hold only decisions relevant for that repository. | ||
|
|
||
| * Good, because specific decisions for specific services and applications are contained within the repo for that project | ||
|
There was a problem hiding this comment. I believe we should have both central repo for system wide architecture decisions and project based ADRs for tactical decisions made for that project. One e.g. of a tactical decision for a project could be about a specific choice made for a domain model applicable only to that project. When ADR is created, the engineer creating it would have to decide if the scope is specific to the service or not specific to the project and decide accordingly. There was a problem hiding this comment. That sounds great. I guess we can always create a project view (such as https://github.com/orgs/Greenstand/projects/45/views/1) There was a problem hiding this comment. I agree. A hybrid approach would offer good flexibility, and we always have the option of elevating a project-specific decision to the org-wide repo either during review, or at a later date by quoting/linking the original decision in a new org ADR. Searchability/discoverability may prove an issue, but I'm sure we could find a good solution. There was a problem hiding this comment. I like the idea of making a project for all ADRs, and making adding a new ADR to the project board a standard part of the ADR creation process. There was a problem hiding this comment. We could use project boards to manage ADRs that span a couple of repos but not necessarily organization-wide while having individual repos with their own ADR as it pertains to it. I think having a project for all ADRs might possibly get cumbersome? Or the ADR for a particular project could be on the project board of that project as opposed to having its own project board There was a problem hiding this comment. @Kpoke If the organization-wide board becomes cumbersome, we can create filtered sub-boards within that board to break out the ADRs more nicely. We can also investigate automation that takes any new PR that adds a file to the decisions/ folder, and adds that PR to our project board. |
||
| * Bad, because ADRs are spread apart in many different repositories, making them hard to review en masse | ||
|
|
||
| <!-- | ||
| ## Links <!-- optional --> | ||
|
|
||
| * {Link type} {Link to ADR} <!-- example: Refined by [ADR-0005](0005-example.md) --> | ||
| * … <!-- numbers of links can vary --> | ||
| --> | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps we can tag each ADR with the repositories or project areas affected.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can tag the ADR PRs, but once they are merged how would the tags operate?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not an ideal solution, but we can still search closed PRs by label.
Perhaps we could use a basic hashtag format within the file for searching, and either add search page links to the README or set up a GitHub action to maintain repo-specific lists.