Gabriel Radureau
a24b4fdb3b
## Summary Homogenize all 23 ADRs to a single canonical header format, and rewrite `adr/README.md` to match the actual state of the corpus. This is **Tâche 7** of the ARCODANGE Phase 1 migration (Claude Code → Mistral Vibe). Independent from PR #17 (Tâche 6 — restructure AGENTS.md) — both can merge in any order. No code changes; only documentation. ## Changes ### 1. Homogenize 21 ADR headers (commit `db09d0a`) The audit (Tâche 6 Phase A, Mistral intent-router agent, 2026-05-02) had identified **3 inconsistent header formats** : - **F1** — list bullets (`* Status:` / `* Date:` / `* Deciders:`) : 11 ADRs (0001-0008, 0011, 0014, 0023) - **F2** — bold fields (`**Status:**` / `**Date:**` / `**Authors:**`) : 9 ADRs (0009, 0010, 0012, 0013, 0015, 0016, 0017, 0018, 0019) - **F3** — dedicated section (`## Status\n**Value** ✅`) : 5 ADRs (0020, 0021, 0022, 0024, 0025) Plus mixed metadata names (Authors / Deciders / Decision Date / Implementation Date / Implementation Status / Last Updated) and decorative emojis on status values made the corpus hard to scan or template against. **Canonical format adopted** (see `adr/README.md` for full template) : ```markdown # NN. Title **Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN> **Date:** YYYY-MM-DD **Authors:** Name(s) [optional **Field:** ... lines] ## Context... ``` **Transformations applied** (via `/tmp/homogenize-adrs.py` script, 23 files scanned, 21 modified — 0010 and 0012 were already conform) : - F1 list bullets → bold fields - F2 cleanup : `**Deciders:**` → `**Authors:**`, strip status emojis - F3 sections : `## Status\n**Value** ✅` → `**Status:** Value` (single line) - Strip decorative emojis from `**Status:**` and `**Implementation Status:**` - Convert `* Last Updated:` / `* Implementation Status:` / `* Decision Drivers:` / `* Decision Date:` to bold - Date typo fix : `2024-04-XX` → `2026-04-XX` for ADRs 0018, 0019 (off-by-2-years in original) - Normalize multiple blank lines after header (max 1) **ADR body content is preserved unchanged.** Only headers transformed. ### 2. Rewrite `adr/README.md` (commit `d64ab02`) Previous README had multiple inconsistencies : - Index table listed wrong titles for ADRs 0010-0021 (looked like an aspirational forecast that never matched reality — e.g. "0011 = Trunk-Based Development" but real 0011 is absent and Trunk-Based Development is actually 0017) - Listed entries for ADRs 0011 (validation library) and 0014 (gRPC) but **these files do not exist** in the repo - 0024 (BDD Test Organization) was missing from the detail list - Template still showed the obsolete F1 format (`* Status:`) - Decorative emojis on every status entry Rewrite : - Index table **regenerated from actual file contents** (title from H1, status from `**Status:**` line) — emoji-free, accurate - Notes that 0011 / 0014 are not currently in use (reserved) - Updated template block matches the canonical format - Status Legend extended with `Approved`, `Partially Implemented`, `Deferred` - Added note that 0026 is the next free number for new ADRs ## Test plan - [x] All 23 ADRs follow `**Status:**` / `**Date:**` / `**Authors:**` (verified via grep) - [x] No more occurrences of `* Status:` (F1) or `## Status` (F3) in any ADR header - [x] No more emojis on `**Status:**` lines - [x] `adr/README.md` index links resolve to existing files (no more 0011 / 0014 dead links) - [x] Pre-commit hooks pass (`go mod tidy`, `go fmt`, `swag fmt`) ## Migration context Part of Phase 1 of the ARCODANGE migration from Claude Code to Mistral Vibe. Tâche 7 of the curriculum. Independent from PR #17 (which restructures `AGENTS.md`). The two PRs touch disjoint files — no merge conflict expected when both are merged. 🤖 Generated with [Claude Code](https://claude.com/claude-code) (Opus 4.7, 1M context). Mistral Vibe (intent-router agent / mistral-medium-3.5) did the original audit identifying the 3 formats during Tâche 6 Phase A. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-Authored-By: Mistral Vibe (devstral-2 / mistral-medium-3.5) Reviewed-on: #18 Co-authored-by: Gabriel Radureau <arcodange@gmail.com> Co-committed-by: Gabriel Radureau <arcodange@gmail.com>
114 lines
5.1 KiB
Markdown
114 lines
5.1 KiB
Markdown
# Architecture Decision Records (ADRs)
|
|
|
|
This directory contains the Architecture Decision Records (ADRs) for the dance-lessons-coach project. Each ADR captures a structurally important decision, its context, and its consequences.
|
|
|
|
## Index
|
|
|
|
| ADR | Title | Status |
|
|
|-----|-------|--------|
|
|
| [0001](0001-go-1.26.1-standard.md) | Use Go 1.26.1 as the standard Go version | Accepted |
|
|
| [0002](0002-chi-router.md) | Use Chi router for HTTP routing | Accepted |
|
|
| [0003](0003-zerolog-logging.md) | Use Zerolog for structured logging | Accepted |
|
|
| [0004](0004-interface-based-design.md) | Adopt interface-based design pattern | Accepted |
|
|
| [0005](0005-graceful-shutdown.md) | Implement graceful shutdown with readiness endpoints | Accepted |
|
|
| [0006](0006-configuration-management.md) | Use Viper for configuration management | Accepted |
|
|
| [0007](0007-opentelemetry-integration.md) | Integrate OpenTelemetry for distributed tracing | Accepted |
|
|
| [0008](0008-bdd-testing.md) | Adopt BDD with Godog for behavioral testing | Accepted |
|
|
| [0009](0009-hybrid-testing-approach.md) | Combine BDD and Swagger-based testing | Partially Implemented |
|
|
| [0010](0010-api-v2-feature-flag.md) | API v2 Feature Flag Implementation | Accepted |
|
|
| [0012](0012-git-hooks-staged-only-formatting.md) | Git Hooks: Staged-Only Formatting | Accepted |
|
|
| [0013](0013-openapi-swagger-toolchain.md) | OpenAPI/Swagger Toolchain Selection | Partially Implemented |
|
|
| [0015](0015-cli-subcommands-cobra.md) | CLI Subcommands and Flag Management with Cobra | Implemented |
|
|
| [0016](0016-ci-cd-pipeline-design.md) | CI/CD Pipeline Design for Multi-Platform Compatibility | Accepted |
|
|
| [0017](0017-trunk-based-development-workflow.md) | Trunk-Based Development Workflow for CI/CD Safety | Approved |
|
|
| [0018](0018-user-management-auth-system.md) | User Management and Authentication System | Proposed |
|
|
| [0019](0019-postgresql-integration.md) | PostgreSQL Database Integration | Proposed |
|
|
| [0020](0020-docker-build-strategy.md) | Docker Build Strategy: Traditional vs Buildx | Accepted |
|
|
| [0021](0021-jwt-secret-retention-policy.md) | JWT Secret Retention Policy | Proposed |
|
|
| [0022](0022-rate-limiting-cache-strategy.md) | Rate Limiting and Cache Strategy | Proposed |
|
|
| [0023](0023-config-hot-reloading.md) | Config Hot Reloading Strategy | Proposed |
|
|
| [0024](0024-bdd-test-organization-and-isolation.md) | BDD Test Organization and Isolation Strategy | Proposed |
|
|
| [0025](0025-bdd-scenario-isolation-strategies.md) | BDD Scenario Isolation Strategies | Proposed |
|
|
|
|
> **Note** : numbers `0011` and `0014` are not currently in use. Reserved for future ADRs or representing previously deleted entries.
|
|
|
|
## What is an ADR?
|
|
|
|
An ADR is a document capturing one significant architectural decision: the **context** that motivated it, the **decision** itself, and its **consequences**. ADRs are append-only — once published, an ADR is not edited (except for typo / status updates). New decisions that supersede previous ones are recorded as new ADRs that explicitly link back.
|
|
|
|
## Canonical Format
|
|
|
|
All ADRs follow the canonical format below (homogenized 2026-05-03):
|
|
|
|
```markdown
|
|
# NN. Short title summarising the decision
|
|
|
|
**Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN>
|
|
**Date:** YYYY-MM-DD
|
|
**Authors:** Name(s)
|
|
|
|
[Optional fields, all in `**Field:** value` format:]
|
|
**Decision Drivers:** ...
|
|
**Implementation Status:** ...
|
|
**Implementation Date:** ...
|
|
**Last Updated:** ...
|
|
|
|
## Context and Problem Statement
|
|
|
|
[Describe the context and problem statement.]
|
|
|
|
## Decision Drivers
|
|
|
|
* Driver 1
|
|
* Driver 2
|
|
|
|
## Considered Options
|
|
|
|
* Option 1
|
|
* Option 2
|
|
|
|
## Decision Outcome
|
|
|
|
Chosen option: "Option 1" because [justification].
|
|
|
|
## Pros and Cons of the Options
|
|
|
|
### Option 1
|
|
|
|
* Good, because [argument].
|
|
* Bad, because [argument].
|
|
|
|
### Option 2
|
|
|
|
* Good, because [argument].
|
|
* Bad, because [argument].
|
|
|
|
## Links
|
|
|
|
* Related ADR: [ADR-NNNN](NNNN-slug.md)
|
|
* Issue: [#NN](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/NN)
|
|
```
|
|
|
|
## Status Legend
|
|
|
|
| Status | Meaning |
|
|
|---|---|
|
|
| **Proposed** | Decision is being discussed; no implementation yet. |
|
|
| **Accepted** | Decision has been made; implementation may be pending or in progress. |
|
|
| **Approved** | Same as Accepted; alternative term used in some legacy ADRs. |
|
|
| **Implemented** | Decision is fully implemented and in production. |
|
|
| **Partially Implemented** | Decision is partly implemented; remainder is deferred or pending. |
|
|
| **Rejected** | Decision considered and explicitly rejected. The ADR documents why. |
|
|
| **Deferred** | Decision postponed; revisit later. |
|
|
| **Deprecated** | Decision is no longer relevant; system has moved on. |
|
|
| **Superseded by ADR-NNNN** | Decision has been replaced by another ADR. Always include the link. |
|
|
|
|
## How to Add a New ADR
|
|
|
|
1. Pick the next available number (currently next would be `0026`).
|
|
2. Copy an existing ADR (e.g., `0001-go-1.26.1-standard.md`) as a starting template.
|
|
3. Edit the title, status, date, authors, and content.
|
|
4. Update this `README.md` index with the new ADR.
|
|
5. Commit using gitmoji convention (e.g., `📝 docs(adr): add ADR-0026 about ...`).
|
|
6. Open a PR for review.
|