3. Govern architecture proposals
Date: 2026-10-02
Status
Accepted
Related issue: #6953.
This ADR extends ADR 0001.
Context
Atlantis records architecture decisions but does not distinguish approval to publish a proposal from approval to adopt it. Proposed records lack a defined acceptance authority or final review period. Contributors need a public path from discussion to a decision that permits asynchronous participation.
Feature maturity and compatibility are separate policy questions, covered by ADR 0004. This ADR governs architecture proposals only.
Decision
Publication and discussion
Every ADR links to a primary public issue before publication. Reuse an existing issue when appropriate. The issue links back to the ADR and records open questions, discussion outcomes, and agreed next steps.
| Step | Record |
|---|---|
| Discuss | Describe the problem and alternatives in the primary issue |
| Publish | Review the document for clarity, scope, context, and alternatives; merge it as Proposed |
| Deliberate | Revise the proposal through pull requests and discuss unresolved questions in the issue |
| Decide | Review the exact final text in a separate status-change pull request |
| Record | Merge the status, decision date, rationale, and discussion links; update the primary issue |
Publication does not establish acceptance or start a final review period. Meetings are optional; their outcomes inform public review and are recorded in the issue. Attendance is not required. Material changes discussed in a meeting must be published for asynchronous review.
Contributors may request renewed review in the issue. Maintainers record requested revisions, further review, or deferral with a reason when responding. Review checkpoints may be agreed, but there is no mandatory meeting schedule or response deadline. Inactivity changes neither status nor delivery priority.
Acceptance rule
Acceptance requires all of the following on the status-change pull request:
- Approval of the final text by two distinct maintainers whose role is Maintainer in MAINTAINERS.md. A listing as Core Contributor alone does not establish this authority.
- A final comment period of 14 calendar days on the status-change pull request. The proposer starts it by posting a comment identifying the final revision and the start and end times in UTC, and links that comment from the primary issue. The start cannot precede the announcement. Opening a proposal or merging it as Proposed does not start this period. No separate sponsorship or website countdown is required.
- No outstanding objection from a maintainer. Each objection must be resolved with the objecting maintainer's agreement or explicitly withdrawn by that maintainer. A response or an approving review from someone else does not resolve it.
Material revisions restart the comment period. Editorial corrections may retain it only when both approving maintainers record that they do not change the decision. Both required approvals must cover the final text.
Silence after the period means no additional objection; it does not supply either required approval. Reactions, approval of the publication PR, and meeting attendance do not count as acceptance. An outstanding maintainer objection cannot be overruled under this process; introducing an overrule mechanism requires a separate ADR.
Approvers must be current maintainers and cannot approve their own proposal. With three maintainers, a maintainer-authored proposal requires both other maintainers. Inactivity alone does not withdraw an objection. If the objector leaves the Maintainer role, both approving maintainers must record a disposition of the concern before acceptance; the former maintainer's withdrawal is no longer required. There is no deadline for obtaining approvals.
The decision record links the approvals and comment-period announcement, identifies resolved or withdrawn objections, and states the rationale. Non-maintainer feedback must receive a recorded disposition; maintainers remain responsible for the decision.
Dispositions and implementation
ADRs retain the existing statuses: Proposed, Accepted, Rejected, Superseded, and Deprecated. Substantive rejection uses the same two-maintainer approval, 14-day final review, and objection-resolution requirements as acceptance, with the rejection rationale in the status-change PR. A proposer may instead withdraw a proposal; record it as Rejected with the reason "withdrawn by proposer" through normal document review, without requiring a substantive rejection decision.
After a decision, close the primary issue or identify remaining implementation work. Exploratory implementation can inform discussion, but merging an architecture change requires acceptance of the applicable ADR. Acceptance does not promise implementation priority or delivery.
An ADR that adds to an earlier decision links to it and leaves it Accepted. An accepted replacement marks the earlier ADR Superseded and links both records. Existing ADR statuses do not change through adoption of this process.
Adoption and publication tooling
On acceptance, update the ADR README, template, and contributor guidance. The template requires a Related issue field. The README distinguishes discussion in issues, proposal and decision text in ADRs, and document review in pull requests. Keep the index current. Assign numbers in merge order; open-proposal numbers are provisional. Renumber the ADR and its references before merge if another proposal lands first.
Rendering canonical docs/adr/ records and their statuses on the website, and adding website checks for that path, are separate future work. They do not condition adoption of this process. Website publication must distinguish Proposed records from accepted decisions and retain one editable source.
Minimal example
The following hypothetical example illustrates the record format without depending on feature lifecycle policy.
# N. Store execution history in a relational database
Date: YYYY-MM-DD
## Status
Proposed
Related issue: <primary issue URL>
## Context
Execution history needs transactional updates and queries across projects.
## Decision
Store execution history in a relational database. Preserve existing locking
and authorization requirements.
## Consequences
Operators need database configuration, migration instructions, and a
rollback plan. Database operation adds maintenance work.Publishing this record leaves it Proposed. A later status-change PR sets Accepted and records the decision date, rationale, two approving review links, the final revision and 14-day comment period, and the disposition of objections. The implementation and release-specific lifecycle documentation follow separately.
Consequences
Contributors and maintainers can distinguish publication from acceptance and assess a recorded decision without attending a meeting. Two approvals and a final review period establish a concrete acceptance threshold.
Decisions require explicit maintainer participation and may remain blocked by an unresolved objection. Issue records, review periods, and the ADR index require upkeep. The process sets no response deadline or implementation commitment.
Alternatives considered
| Alternative | Reason not selected |
|---|---|
| Accept through the publication PR | Conflates making a proposal discoverable with adopting it |
| Accept through silence alone | Does not establish the required maintainer approvals |
| Require a meeting for each decision | Limits asynchronous participation and adds scheduling work |
| Permit overriding maintainer objections | Requires a separately agreed authority and decision rule |
| Bundle governance, feature policy, and runtime tooling | Combines independently reviewable decisions |