diff --git a/Readme.md b/Readme.md index 9abfcfd..a7af7f5 100644 --- a/Readme.md +++ b/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/README.md). - 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. diff --git a/adrs/0001-adopt-architecture-decision-records.md b/adrs/0001-adopt-architecture-decision-records.md new file mode 100644 index 0000000..d779fb8 --- /dev/null +++ b/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 still start as a GitHub issue, per the existing [Decision-Making and Voting](../operations/governance.md#decision-making-and-voting) process — but once decided (like the `MAINTAINERS.md` question in #308), the outcome gets written up as an ADR rather than left to live only in 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). diff --git a/adrs/README.md b/adrs/README.md new file mode 100644 index 0000000..f2f34ac --- /dev/null +++ b/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. Raise a GitHub issue proposing the decision. Discussion and voting happen there (or in TOC meetings), per [Decision-Making and Voting](../operations/governance.md#decision-making-and-voting) in the TOC governance document — this doesn't change. +2. Once a decision is reached, open a PR adding the ADR file to this directory, `Status` set to the outcome (`Accepted` or `Rejected`), linking back to the issue. +3. The PR is for recording the decision, not re-litigating it — substantive discussion belongs on the issue. +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 | diff --git a/operations/governance.md b/operations/governance.md index a8025ea..373d967 100644 --- a/operations/governance.md +++ b/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) once decided through the [Decision-Making and Voting](#decision-making-and-voting) process above. See [`adrs/README.md`](../adrs/README.md) for the ADR process and format. ## Processes