Adopt Architecture Decision Records (ADR-0001)

Readme.md

@@ -32,6 +32,7 @@ To support ongoing work, we use the following communication channels:
  - Our overall backlog of work is organised via a [GitHub project board](https://github.com/orgs/finos/projects/39).
  - We use [GitHub discussions](https://github.com/finos/technical-oversight-committee/discussions) as our primary mechanism for discussing and collaboration.
  - We use the email distribution list (toc@lists.finos.org) for announcements (e.g. announcing a meeting).
+ - We record governance and technical decisions with lasting effect as [Architecture Decision Records](/adrs).
  - We use our private Tuesday meetings primarily for TOC planning.
  - We use our public Wednesday meetings primarily for FINOS project and SIG presentations as well as for other community updates.
  - We have ad-hoc meetings as and when they are needed. These will not be minuted.

adrs/0001-adopt-architecture-decision-records.md

@@ -0,0 +1,44 @@
+# ADR-0001: Adopt Architecture Decision Records
+
+**Status:** Accepted
+**Date:** 2026-07-30
+**Deciders:** TOC members (via [#308](https://github.com/finos/technical-oversight-committee/issues/308))
+**Related:** [#308](https://github.com/finos/technical-oversight-committee/issues/308), [#306](https://github.com/finos/technical-oversight-committee/pull/306)
+
+## Context
+
+[#306](https://github.com/finos/technical-oversight-committee/pull/306) surfaced a real disagreement about how `MAINTAINERS.md` should handle contact information. Rather than let that discussion play out only as unstructured PR comments, it was raised as [#308](https://github.com/finos/technical-oversight-committee/issues/308), an issue laid out in an ADR-like structure — context, decision drivers, considered options, a recommendation — to make the tradeoffs explicit and give TOC members a clear basis to weigh in.
+
+That format worked: it produced a focused discussion and a decision the TOC could point back to. In the same issue, it was proposed that the TOC formally adopt ADRs going forward, with this ADR being the first one — a decision to keep making decisions this way.
+
+The TOC already documents outcomes as part of its [Communication & Documentation](../operations/governance.md#communication--documentation) practice, and proposals are already expected to run through GitHub issues per [Decision-Making and Voting](../operations/governance.md#decision-making-and-voting). What was missing was a durable, consistently-structured record of *why* a given decision was made — issue threads are searchable but the reasoning is diffused across comments, and there was no single place to look for "what did the TOC decide about X, and why."
+
+## Decision Drivers
+
+- **Discoverability**: someone asking "why does the TOC do X this way" should be able to find an answer without reconstructing it from issue comment history.
+- **Consistency**: a fixed structure (context, options, decision, consequences) makes proposals easier to evaluate and easier to write, compared to free-form issues.
+- **Fits existing process**: this should extend the TOC's existing issue-based proposal and voting process, not replace it.
+
+## Considered Options
+
+### Option A — Continue using ad hoc GitHub issues
+Keep raising governance proposals as regular issues, without a required structure or a persistent record beyond the issue itself.
+
+- Pros: No new process to maintain; how the TOC already operates.
+- Cons: Reasoning behind past decisions is hard to find later; nothing stops each proposal from being structured differently, which makes them harder to compare or evaluate.
+
+### Option B — Adopt Architecture Decision Records (Chosen)
+Formalize the ADR-style structure used in #308 as the standard way to propose and record TOC decisions with lasting effect, stored as versioned markdown files in this repository.
+
+- Pros: Produces a durable, greppable record of decisions and their rationale, sitting alongside the code/docs it affects. Reuses a well-established open-source pattern rather than inventing something bespoke. Composes with the existing issue/PR-based voting process in [governance.md](../operations/governance.md#decision-making-and-voting) rather than replacing it.
+- Cons: Adds a small amount of process (a template to follow, a file to keep in sync with the outcome) on top of the existing issue-based flow.
+
+## Decision Outcome
+
+**Option B.** ADRs are adopted as the standard format for documenting TOC decisions of lasting governance or technical significance, stored under [`/adrs`](./README.md) in this repository. See [`adrs/README.md`](./README.md) for the process and template.
+
+## Consequences
+
+- Future governance proposals with real tradeoffs (like the `MAINTAINERS.md` question in #308) should be written up as an ADR PR rather than left as an issue thread.
+- The TOC now has one place (`/adrs`) to point to when asked why a given standard or process exists.
+- Existing decisions are not retroactively converted — ADRs apply going forward, though a past decision worth preserving can be written up after the fact, as with the `MAINTAINERS.md` email decision reached in [#308](https://github.com/finos/technical-oversight-committee/issues/308).

adrs/README.md

@@ -0,0 +1,63 @@
+# Architecture Decision Records
+
+This directory holds the Architecture Decision Records (ADRs) for the FINOS Technical Oversight Committee (TOC).
+
+An ADR captures a governance or technical decision made by the TOC that has lasting effect — the kind of thing someone will otherwise have to reconstruct from scattered issue and meeting history later. See [ADR-0001](./0001-adopt-architecture-decision-records.md) for why the TOC adopted this practice.
+
+## When to write one
+
+Write an ADR when a decision:
+
+- Changes a standard, template, or process the TOC asks FINOS projects to follow (e.g. the `MAINTAINERS.md` format)
+- Changes how the TOC itself operates and isn't already covered by [governance.md](../operations/governance.md)
+- Was debated with real tradeoffs, where the reasoning is as valuable as the outcome
+
+Routine operational decisions (scheduling, meeting logistics, individual project votes already covered by [voting.md](../operations/processes/voting/voting.md)) don't need one.
+
+## Process
+
+1. Open a PR adding a new ADR file to this directory with `Status: Proposed`.
+2. Discussion happens on the PR, following the [Decision-Making and Voting](../operations/governance.md#decision-making-and-voting) process in the TOC governance document.
+3. Once a decision is reached, update the `Status` field (`Accepted`, `Rejected`, or `Superseded by ADR-NNNN`) and merge.
+4. ADRs are not deleted once merged, even if superseded — the record of what was decided and why should stay intact. A superseding ADR should link back to the one it replaces.
+
+## Numbering and format
+
+Files are named `NNNN-short-kebab-case-title.md`, numbered sequentially starting at `0001`. Use the next unused number when proposing a new ADR.
+
+Each ADR should follow this structure:
+
+```markdown
+# ADR-NNNN: Title
+
+**Status:** Proposed | Accepted | Rejected | Superseded by ADR-NNNN
+**Date:** YYYY-MM-DD
+**Deciders:** who was involved
+**Related:** links to relevant issues/PRs
+
+## Context
+
+What prompted this decision, and what constraints or prior discussion shaped it.
+
+## Decision Drivers
+
+The factors that matter most in choosing between options.
+
+## Considered Options
+
+Each option considered, with pros and cons.
+
+## Decision Outcome
+
+The option chosen, and why.
+
+## Consequences
+
+What this makes easier, what it makes harder, and any follow-up it creates.
+```
+
+## Index
+
+| ADR | Title | Status |
+| --- | --- | --- |
+| [0001](./0001-adopt-architecture-decision-records.md) | Adopt Architecture Decision Records | Accepted |

operations/governance.md

@@ -112,6 +112,7 @@ The key responsibilities of the TOC are summarized below:
 - Decisions, outcomes, and policies must be documented in the TOC GitHub repository
 - Charters, reports, and other key documentation should be maintained and updated on the TOC GitHub repository regularly
 - In the event that a requirement from this document is not explicitly captured herein, clarifying documentation may be captured in the TOC repository, where it should be considered equally authoritative unless conflicting with this document.
+- Governance or technical decisions with lasting effect — for example, a standard or template the TOC asks FINOS projects to follow — should be recorded as an [Architecture Decision Record](/adrs) (ADR), proposed and discussed as a PR following the process in [`adrs/README.md`](/adrs/README.md), subject to the voting process below.
 
 ## Processes