ADR-0000: Use ADRs to Document Architectural Decisions
| Status | Accepted |
|---|---|
| Date | 2024-01-01 |
| Author | @leonwong282 |
| Deciders | Project maintainers |
Context
As this project grows, we need a way to document important architectural decisions so that:
- New contributors understand why things are built a certain way
- We don't repeatedly discuss the same decisions
- We have a historical record of the project's evolution
- Decisions can be reviewed and updated over time
Decision Drivers
- Need for transparency in decision-making
- Desire to reduce onboarding time for new contributors
- Want to avoid "why did we do it this way?" discussions
- Need a lightweight, developer-friendly documentation format
Considered Options
- Architecture Decision Records (ADRs) - Markdown files in the repo
- Wiki pages - GitHub Wiki or external wiki
- Issue comments - Document decisions in GitHub issues
- Confluence/Notion - External documentation platform
Decision Outcome
Chosen option: "Architecture Decision Records (ADRs)", because they are:
- Version-controlled alongside the code
- Reviewable through the normal PR process
- Lightweight and easy to create
- Searchable and discoverable
- Not dependent on external services
Positive Consequences
- Decisions are documented in a consistent format
- History is preserved in git
- Easy to reference in code comments and PRs
- No additional tooling required
Negative Consequences
- Requires discipline to create ADRs for significant decisions
- Another thing to maintain (mitigation: keep the process lightweight)
Pros and Cons of the Options
ADRs in Repository
- ✅ Version controlled with code
- ✅ Goes through PR review
- ✅ No external dependencies
- ✅ Portable if we change platforms
- ❌ Requires contributor discipline
Wiki Pages
- ✅ Easy to edit
- ❌ Separate from code repository
- ❌ No PR review process
- ❌ Often becomes outdated
Issue Comments
- ✅ Already in GitHub
- ❌ Hard to find later
- ❌ Gets lost in conversation
- ❌ No structured format
External Platform
- ✅ Rich editing features
- ❌ Another tool to maintain
- ❌ Access control complexity
- ❌ Vendor lock-in