-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture Decisions
This page catalogs the Architecture Decision Records (ADRs) for the git-adr project itself. These decisions document the technical choices made during development, providing transparency into why git-adr works the way it does.
| Status | Count |
|---|---|
| Accepted | 14 |
| Proposed | 1 |
| Total | 15 |
These foundational decisions shape git-adr's architecture and behavior.
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Use subprocess to the git binary for all git operations instead of pygit2 or GitPython.
Key Consequences:
- Industry standard approach (5 of 6 major git extensions use this)
- Zero additional dependencies
- Full feature parity with git CLI including notes operations
- Inherits user's git configuration and credentials automatically
- No GPL license concerns (pygit2/libgit2 is GPLv2)
Alternatives Considered:
- pygit2: High performance but adds libgit2 dependency and GPLv2 license
- GitPython: Still shells out internally, Windows reliability issues
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Attach ADRs to the repository root tree object, with related commit SHAs stored in ADR metadata.
Key Consequences:
- ADRs survive rebase/amend operations
- ADRs exist independently of specific commits
- Supports ADRs that precede or span multiple commits
- Requires index to map ADR IDs to notes
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Use YAML frontmatter followed by Markdown body for storing ADRs in git notes.
Key Consequences:
- Human-readable in terminal via
git log - Structured metadata for programmatic access
- Compatible with union merge strategy
- Standard format matching file-based ADR tools
- Requires YAML parsing dependency
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Store artifacts in refs/notes/adr-artifacts with content-addressed references in ADR metadata.
Key Consequences:
- Main ADR notes stay small and text-based
- Content deduplication via SHA256 addressing
- Size limits enforceable separately
- Additional namespace to sync
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Migrate from click to Typer.
Key Consequences:
- Type hints provide better IDE support
- Automatic shell completion generation
- Built-in Rich integration for formatting
- Less boilerplate than click
- Built on click (same underlying engine)
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Support multiple input modes for git adr new:
- Editor mode (default) - Opens configured editor
- File input -
--file path/to/content.md - Stdin input -
cat file.md | git adr new "Title" - Preview mode -
--previewshows template without creating
Key Consequences:
- Works with any editor (terminal or GUI)
- Enables scripting and automation
- No editor lock-in
- Template preview helps users understand formats
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Priority order: OpenAI -> Anthropic -> Other providers -> Ollama
Key Consequences:
- OpenAI has largest user base, gets most attention
- Anthropic as strong secondary option
- Ollama last (local use, no API key needed)
- All providers supported via langchain abstraction
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: When AI is enabled, git adr draft defaults to interactive elicitation mode where the AI asks sequential questions:
- "What problem are you solving?"
- "What options have you considered?"
- "What's driving this decision?"
- "What are the trade-offs/consequences?"
Then synthesizes answers into a complete ADR. --batch flag available for scripted usage.
Key Consequences:
- AI acts as collaborative partner, not just generator
- Ensures users think through all decision aspects
- Higher quality ADRs through guided reflection
- Natural for users unfamiliar with ADR structure
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: git adr init automatically configures:
-
remote.origin.fetchto include notes refs -
remote.origin.pushto include notes refs -
notes.rewriteReffor rebase safety -
notes.rewrite.rebaseandnotes.rewrite.amend
Key Consequences:
- Users don't lose ADRs due to misconfiguration
- Notes automatically sync with regular push/pull
- Modifies user's git config (expected behavior for init)
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli | Type: Scope Creep
Decision: Implement git-lfs style distribution with:
- Makefile for build/install/release targets
- install.sh script for tarball installation
- release.yml GitHub Actions workflow for automated releases
Key Consequences:
- Familiar pattern for git extension users
- Single tarball contains all artifacts
- Works without PyPI access
- Significant scope increase (~10 hours of work)
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli
Decision: Lower minimum Python version from 3.12+ to 3.11+.
Key Consequences:
- Broader user base (3.11 still widely used)
- Longer support window
- Cannot use 3.12+ only features (few relevant ones)
These decisions were added during implementation based on real needs discovered during development.
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli | Type: Scope Creep
Decision: Add git adr rm <id> [--force] command to remove ADRs from git notes.
Implementation:
- Interactive confirmation by default showing ADR title, status, and warnings
-
--forceflag to skip confirmation (for scripting) - Warnings for: linked commits, superseding relationships
Classification: Acceptable scope creep because:
- Aligns with tool's philosophy (manage ADRs without raw git notes)
- User-requested based on real need
- Similar pattern to existing
artifact-rmcommand
Status: Accepted | Date: 2025-12-15 | Tags: git-adr-cli | Type: Scope Creep
Decision: Raise coverage target from 90% to 95% and add tests to meet it.
Implementation:
- Added
tests/test_completion.py(12 tests) for shell completion code - Added
tests/test_rm_command.py(14 tests) for new rm command - Final coverage: 95.19%
Classification: Acceptable scope creep because:
- Higher quality is always beneficial
- CI already enforced this requirement
- Tests caught real issues during development
Status: Accepted | Date: 2025-12-15 | Tags: documentation, process
Decision: Use Architecture Decision Records (ADRs) stored in git notes, as described by git-adr.
Key Consequences:
- Decisions are documented and searchable
- Context is preserved for future team members
- ADRs don't clutter the repository file tree
- Natural integration with git workflow
- Team members need to learn git-adr commands
To read the full content of any ADR:
# Show specific ADR
git adr show adr001-use-subprocess-to-git-binary-for-git-ope
# List all ADRs
git adr list
# Search ADRs
git adr search "subprocess"When making architectural changes to git-adr:
- Create an ADR documenting the decision
- Get team review on the proposed ADR
- Update status to accepted/rejected
- Link implementing commits to the ADR
# Create new decision
git adr new "Your Decision Title"
# After implementation, link commits
git adr link <adr-id> <commit-sha>- Getting Started - How to use git-adr
- ADR Templates - Template formats for ADRs
- ADR Primer - Introduction to ADRs
Architecture Decisions
...and 24 more