Skip to content

Roadmap Process

This document defines how roadmap plans move from active planning to archived history.

Scope

Use this process for files in:

  • docs/roadmaps/ (active or in-progress plans)
  • docs/roadmaps/archive/ (completed or superseded plans)
  • docs/meta/ROADMAP.md (high-level now/later/history summary)

Lifecycle

  1. Create or update an active roadmap in docs/roadmaps/.
  2. Execute work and update task checkboxes continuously.
  3. When work is finished or superseded, archive the roadmap.
  4. Reflect final status in docs/meta/ROADMAP.md.
  5. Add release notes in docs/meta/CHANGELOG.md.

Status Rules

  • Active: Work is in progress and still the source of truth.
  • Completed: All roadmap tasks are done.
  • Superseded: Plan is no longer active because newer plans/releases replaced it.
  • Archived: File moved to docs/roadmaps/archive/ with a final status.

Archive Rules

When archiving:

  1. Move the file into docs/roadmaps/archive/.
  2. Use a stable filename format: <NN>-<version-or-topic>.md.
  3. Set an explicit top-level status line:
  4. **Status:** ✅ Completed
  5. or **Status:** 📦 Superseded
  6. Add an archive date.
  7. Ensure unchecked items are either:
  8. completed ([x]), or
  9. explained as intentionally superseded.

Completion Checklist

  • Task list accurately reflects what shipped.
  • docs/meta/ROADMAP.md updated.
  • docs/meta/CHANGELOG.md updated.
  • Related docs/ADRs updated.
  • Tests and lint run successfully.

Notes

  • Avoid leaving stale Active plans in docs/roadmaps/.
  • Keep roadmap history concise; use ADRs for long-form decision rationale.