ADR process

Context

TPA has been using the TPA-RFC process since 2020 to discuss and document policy decisions. The process has stratified into a process machinery that feels too heavy and cumbersome.

Jacob Kaplan-Moss's review of the RFC process in general has identified a set of problems that also affect our TPA-RFC process:

RFCs "doesn’t include any sort of decision-making framework"
"RFC processes tend to lead to endless discussion"
RFCs "rewards people who can write to exhaustion"
"these processes are insensitive to expertise", "power dynamics and power structures"

As described in ADR-100: template, the TPA-RFC process doesn't work so well for us. ADR-100 describes a new template that should be used to record decisions, but this proposal here describes how we reach that decision and communicate it to affected parties.

Decision

Major decisions are introduced to stakeholders in a meeting, smaller ones by email. A delay allows people to submit final comments before adoption.

More Information

Discussion process

Major proposals should generally be introduced in a meeting including the decision maker and "consulted" people. Smaller proposals can be introduced with a simple email.

After the introduction, the proposal can be adjusted based on feedback, and there is a delay during which more feedback can be provided before the decision is adopted.

In any case, an issue MUST be created in the issue tracker (currently GitLab) to welcome feedback. Feedback must be provided in the issue, even if the proposal is sent by email, although feedback can of course be discussed in a meeting.

In case a proposal is discussed in a meeting, a comment should be added to the issue summarizing the arguments made and next steps, or at least have a link to the meeting minutes.

Stakeholders definitions

Each decision has three sets of people, roughly following the RACI matrix (Responsible, Accountable, Consulted, Informed):

decision-makers: who makes the call. is generally the team lead, but can (and sometimes must) include more decision makers
consulted: who can voice their concerns or influence the decision somehow. generally the team, but can include other stakeholders outside the team
informed: affected parties that are merely informed of the decision

Possible statuses

The statuses from TPA-RFC-1: RFC process (draft, proposed, standard, rejected, obsolete) have been changed. The new set of statuses is:

draft
proposed
rejected
approved (previously standard)
obsolete
superseded by ... (new)

This was the state transition flowchart in TPA-RFC-1:

flowchart TD
    draft --> proposed
    proposed --> rejected(((rejected)))
    proposed --> standard
    draft --> obsolete(((obsolete)))
    proposed --> obsolete
    standard --> obsolete

Here is what it looks like in the ADR process:

flowchart TD
    draft --> proposed
    proposed --> rejected(((rejected)))
    proposed --> approved
    draft --> obsolete(((obsolete)))
    proposed --> obsolete
    approved --> obsolete
    approved --> superseded(((superseded)))

Mutability

In general, ADRs are immutable, in that once they have been decided, they should not be changed, within reason.

Small changes like typographic errors or clarification without changing the spirit of the proposal are fine, but radically changing a decision from one solution to the next should be done in a new ADR that supersedes the previous one.

This does not apply to transitional states like "draft" or "proposed", during which major changes can be made to the ADR as long as they reflect the stakeholder's deliberative process.

Review of past proposals

Here's a review of past proposals and how they would have been made differently in the ADR process.

at first, we considered amending TPA-RFC-56: large file storage to document the switch from MinIO to GarageHQ (see tpo/tpa/wiki-replica!103), but ultimately (and correctly) a new proposal was made, TPA-RFC-96: Migrating from MinIO to GarageHQ
TPA-RFC-1 was amended several times, for example TPA-RFC-9: "proposed" status and small process changes introduced the "proposed" state, that RFCs are mutable, and so on. in the future, a new proposal should be made instead of amending a past proposal like this, although a workflow graph could have been added without making a proposal and the "obsolete" clarification was a fine amendment to make on the fly
TPA-RFC-12: triage and office hours modified TPA-RFC-2 to introduce office hours and triage. those could have been made in two distinct, standalone ADRs and TPA-RFC-2 would have been amended to refer to those
TPA-RFC-28: Alphabetical triage star of the week modified TPA-RFC-2 to clarify the order of triage, it could have simply modified the ADR (as it was in the spirit of the original proposal) and communicated that change separately
TPA-RFC-80: Debian trixie upgrade schedule and future "upgrade schedules" should have separate "communications" (most of the RFC including "affected users", "notable changes", "upgrade schedule", "timeline") and "ADR" documents (the rest: "alternatives considered", "costs", "approvals")
mail proposals have been a huge problem in the RFC process; TPA-RFC-44: Email emergency recovery, phase A, for example, is 5000 words long and documents various implementation details, cost estimates and possible problems, while at the same time trying to communicate all those changes to staff. those two aspects would really have benefited from being split apart in two different documents.
TPA-RFC-91: Incident response led to somewhat difficult conversations by email, should have been introduced in a meeting and, indeed, when it was discussed in a meeting, issues were better clarified and resolved

Note that this proposal is part of a set of 3 complementary proposals:

This proposal supersedes TPA-RFC-1: RFC process.

Metadata

status: approved
decision-date: 2025-12-08 (in two weeks)
decision-makers: TPA team lead
consulted: tpa-team@lists.torproject.org, director
informed: tor-project@lists.torproject.org
forum-url: https://gitlab.torproject.org/tpo/tpa/team/-/issues/41428

Keyboard shortcuts