Repository navigation
Adopt Architecture Decision Records (ADR-0001) - #314
Merged
Merged
Conversation
Formalizes the ADR-style structure used in finos#308 as the standard way to propose and record TOC decisions with lasting effect, per the agreement reached in that issue's discussion. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Formalizes Architecture Decision Records as the TOC’s standard for documenting lasting decisions.
Changes:
- Adds ADR guidance, workflow, format, and numbering.
- Adds ADR-0001 documenting ADR adoption.
- Links ADR documentation from the README and governance materials.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Summary | Review |
|---|---|---|
Readme.md |
Links ways-of-working guidance to ADRs. | Nit (3 votes): use a repository-relative link instead of a host-root URL. |
operations/governance.md |
Establishes ADR usage in governance. | Moderate (3 votes): fix host-root links and preserve issue-based proposal and discussion, with PRs recording the ADR. |
adrs/README.md |
Defines ADR usage and workflow. | Moderate (3 votes): keep the issue as the proposal, discussion, and voting venue; use the PR for the durable ADR record. |
adrs/0001-adopt-architecture-decision-records.md |
Records the ADR adoption decision. | No final comments. |
Suppressed comments (1)
adrs/0001-adopt-architecture-decision-records.md:3
- The process documented in
adrs/README.mdsays new ADR PRs start asProposedand only change status once the decision is reached before merge. This file is alreadyAcceptedwhile this PR is the artifact being proposed/reviewed, and the index repeatsAccepted, so the repository can claim a decision before the required vote/merge; keep both statusesProposeduntil approval (or document an explicit bootstrap exception).
**Status:** Accepted
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Proposals still go through a GitHub issue for discussion and voting per governance.md's Decision-Making and Voting process; the ADR PR only records the outcome once decided. Also fixes broken host-root links in governance.md.
psmulovics
approved these changes
Aug 21, 2026
psmulovics
left a comment
psmulovics
left a comment
Contributor
There was a problem hiding this comment.
Well done, @rocketstack-matt , this looks great!
11 of 20 tasks
|
|
||
| **Status:** Accepted | ||
| **Date:** 2026-07-30 | ||
| **Deciders:** TOC members (via [#308](https://github.com/finos/technical-oversight-committee/issues/308)) |
Contributor
There was a problem hiding this comment.
Unless I'm missing something in the comment thread, #308 is unrelated to the decision to start tracking ADRs here
Suggested change
| **Deciders:** TOC members (via [#308](https://github.com/finos/technical-oversight-committee/issues/308)) | |
| **Deciders:** TOC members (via [#314](https://github.com/finos/technical-oversight-committee/issues/314)) |
Contributor
|
This was adopted by silent consensus on the Aug 26 FINOS TOC call. |
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Formalizes the ADR-style structure used in #308 as the TOC's standard way to propose and record decisions with lasting effect, per the agreement reached in that issue's discussion (@psmulovics: "I am all for ADRs").
adrs/directory with aREADME.mdcovering when to write an ADR, the proposal/voting process (extending the existing process ingovernance.md), and the file format/numbering conventionadrs/0001-adopt-architecture-decision-records.md— the first ADR, documenting this decision itselfoperations/governance.md(Communication & Documentation) andReadme.md(Ways of Working) to point to/adrsas where these are recordedThis does not change the existing issue-based proposal/voting process in
governance.md— ADRs sit on top of it as the record of decisions with lasting effect, not a replacement for how the TOC discusses and votes.A second ADR capturing the actual
MAINTAINERS.mdemail decision from #308 will follow as a separate PR once this one is reviewed.Related: #308, #306
Test plan
adrs/README.md,adrs/0001-...md,governance.md, andReadme.mdresolve correctly on GitHubadrs/README.mdmatches what was discussed in ADR: How MAINTAINERS.md should handle contact information #308