Architecture Decision Records

These records reflect current proposals and decisions from main. Acceptance does not imply release availability; check the release documentation for supported features.

Architecture Decision Records (ADRs) preserve important design choices and their tradeoffs. Atlantis adopted them in ADR 0001.

Index

ADR	Title	Status
0001	Record architecture decisions	Accepted
0002	API Enhancement and Drift Detection	Proposed
0003	Govern architecture proposals	Accepted
0004	Govern feature lifecycles	Accepted

Update this table when adding or changing an ADR.

Which process should I use?

Change	Process
Bug fixes, docs, tests, CI, dependency updates, and behavior-preserving refactors	Open a pull request.
New user-visible behavior, flags, or commands	Agree on the change in an issue, then open a pull request.
A change matching the criteria below	Open an issue, submit an ADR, then implement it after the ADR is accepted.

The decision matters more than the diff size.

When is an ADR required?

Write an ADR when a change:

• changes persisted data, migrations, or on-disk layout;
• makes a breaking change to an API, config schema, server flag, default, or webhook contract;
• changes concurrency or locking behavior;
• adds a required runtime service, plugin, or extension point;
• changes authentication, authorization, secret handling, command execution, or webhook validation;
• is irreversible or reverses an accepted ADR.

An ADR is not required for bug fixes, additive optional fields, default-off features, performance work with unchanged behavior, refactors, tests, docs, tooling, CI, or dependency updates.

If unsure, open an issue before starting a large implementation.

Submit an ADR

1. Agree on the problem in an issue.
2. Copy template.md to docs/adr/NNNN-short-title.md.
3. Use the next number after the latest merged ADR. Numbers in open proposals are provisional; renumber the record, references, and index before merge if another ADR lands first.
4. Open a pull request with status Proposed and update the index above.

Keep the ADR focused on one decision. Put implementation details in the issue or implementation pull request.

Statuses

• Proposed: under discussion.
• Accepted: approved by the project.
• Rejected: considered and declined.
• Superseded by NNNN: replaced by a later ADR.
• Deprecated: no longer applies.

Merge accepted and rejected ADRs so both decisions remain discoverable. Do not rewrite them later; supersede them with a new ADR.

ADRs follow normal pull request review rules. Link accepted ADRs from their implementation pull requests.

View source