|
1 | | -# Roadmap process — keeping GitHub in sync with the roadmap |
| 1 | +# Roadmap process — GitHub is the source of truth |
2 | 2 |
|
3 | | -How we track planned work, and how the GitHub surfaces stay in sync with the canonical roadmap. |
| 3 | +How we track features and releases. **Changed 2026-10-02:** status, priority and target release |
| 4 | +moved from `spec/roadmap.md` into GitHub. The file-based registry had drifted from both the code |
| 5 | +and the issues (an audit that day found six FRs shipped while the file still listed them as |
| 6 | +planned or active, and eight live FRs with no issue at all). One place to update is the fix. |
4 | 7 |
|
5 | | -## The model: one source of truth, mirrored |
| 8 | +## Where each fact lives |
6 | 9 |
|
7 | | -**`spec/roadmap.md` is the single source of truth.** It holds the **FR registry** (every feature |
8 | | -request + status + target release + tracking issue), the **Shipped / Active / Planned** detail, and |
9 | | -the **Release plan (1.0 → 1.x)**. Every roadmap fact lives here; the GitHub surfaces *mirror* it. |
10 | | - |
11 | | -Three GitHub surfaces mirror the roadmap, each with one job: |
12 | | - |
13 | | -| Surface | Role | Maps to | |
| 10 | +| Fact | Lives in | Not in | |
14 | 11 | |---|---|---| |
15 | | -| **Milestones** | the releases | `1.0` `1.1` `1.2` `1.3` `1.4` `1.x (later)` (= the Release plan) | |
16 | | -| **Issues** | one per FR (execution unit) | a row in the FR registry; label `FR` + an `area:*` label; milestone = target release; body links the design spec | |
17 | | -| **Project board** | a saved view (Now / Next / Later, grouped by milestone) | a view over the `FR`-labelled issues | |
| 12 | +| A feature exists, its scope summary, its status | the GitHub **issue**, labelled `FR` | `spec/roadmap.md` | |
| 13 | +| Target release | the issue's **milestone** (`1.1`, `1.2`, `1.3`, `1.4`, `1.x (later)`) | `spec/roadmap.md` | |
| 14 | +| Work in progress | the **MetaObjects Roadmap** project board's `Status` field (Todo / In progress / Done) | — | |
| 15 | +| The design (why and how) | `docs/superpowers/specs/*`, ADRs in `spec/decisions/*` — linked from the issue, never copied into it | the issue body | |
| 16 | +| Release direction, FR number → issue → spec index, future themes, history | `spec/roadmap.md` | — | |
| 17 | +| What shipped in which version | `CHANGELOG.md` | — | |
18 | 18 |
|
19 | | -Design depth (the *why* and *how*) lives in `docs/superpowers/specs/*` and ADRs in |
20 | | -`spec/decisions/*` — issues link to these, they are not duplicated into issues. |
| 19 | +**An issue labelled `FR` with no milestone is untriaged.** Triage means giving it a milestone or |
| 20 | +closing it. |
21 | 21 |
|
22 | | -## Current GitHub state (bootstrapped 2026-06-13) |
| 22 | +## FR numbers |
23 | 23 |
|
24 | | -- **Milestones:** `1.0`(#1) `1.1`(#2) `1.2`(#3) `1.3`(#4) `1.4`(#5) `1.x (later)`(#6). |
25 | | -- **Labels:** `FR`, `area:metamodel`, `area:serializers`, `area:ui`, `area:grid`, `area:perf`, |
26 | | - `area:tooling`, `area:codegen`. |
27 | | -- **Issues:** one per planned FR — FR-019→#5, FR-020→#6, FR-021→#7, FR-022→#8, FR-023→#9, |
28 | | - FR-024→#10, FR-025→#11, FR-026→#12, FR-027→#13, FR-028→#14, FR-029→#15, FR-030→#16, |
29 | | - FR-031→#17, MCP→#18. |
| 24 | +A feature gets an `FR-0NN` number when it gets a design spec, because the number names the spec |
| 25 | +file and is cited across docs. Small feature requests can stay as plain `FR`-labelled issues |
| 26 | +with no number. Allocate the next number as the highest in `spec/roadmap.md`'s feature index + 1. |
30 | 27 |
|
31 | | -## Sync rules (do these together, in the same change) |
| 28 | +## The rules |
32 | 29 |
|
33 | | -1. **Adding an FR.** Allocate the next FR number (highest in the registry + 1 — currently the next |
34 | | - is **FR-032**). In the *same* PR: add a registry row + a `## Planned` entry + a Release-plan |
35 | | - slot in `spec/roadmap.md`, write/locate the design spec under `docs/superpowers/specs/`, and |
36 | | - create the issue: |
| 30 | +1. **New feature.** Create the issue first, labelled `FR` plus an `area:*` label, with a |
| 31 | + milestone if one is known: |
37 | 32 | ```sh |
38 | | - gh issue create --title "FR-0NN — <title>" \ |
39 | | - --body "<one-line summary> |
40 | | -
|
41 | | - **Spec / design:** <blob URL of the spec> |
42 | | - **Target release:** <milestone> |
43 | | -
|
44 | | - _Tracked in spec/roadmap.md (FR registry); status lives there._" \ |
45 | | - --milestone "<1.x>" --label "FR,area:<x>" |
| 33 | + gh issue create -R metaobjectsdev/metaobjects \ |
| 34 | + --title "FR-0NN — <title>" --label "FR,area:<x>" --milestone "<1.x>" \ |
| 35 | + --body-file <file> # one-paragraph summary, then the spec link and the target release |
46 | 36 | ``` |
47 | | - Put the issue number back into the registry row. |
48 | | - |
49 | | -2. **Changing status or target release.** Update the registry row (status/release) **and** move the |
50 | | - issue's milestone (`gh issue edit <n> --milestone "<new>"`). The roadmap row is authoritative; if |
51 | | - the two disagree, the roadmap wins and the issue is corrected. |
52 | | - |
53 | | -3. **Shipping an FR.** Move it from Planned → Shipped in `spec/roadmap.md` (with the ship note), flip |
54 | | - the registry status to ✅, and `gh issue close <n>` with a comment linking the shipping commit/PR. |
55 | | - |
56 | | -4. **Cutting a release.** Close the milestone when its issues are done; bump the registry rows to ✅. |
57 | | - |
58 | | -**Rule of thumb:** a PR that changes an FR's existence, status, or release **must** edit |
59 | | -`spec/roadmap.md`. The GitHub change (issue/milestone) accompanies it but is never the only record. |
60 | | - |
61 | | -## Project board — one-time setup (manual) |
62 | | - |
63 | | -The board could not be created via API from CI: the available token has |
64 | | -`repo`/`admin:org`/`workflow` scopes but **not `project`** (Projects v2 mutations require the |
65 | | -`project` scope). To create + auto-populate it once: |
66 | | - |
67 | | -1. (If scripting later) grant the scope: `gh auth refresh -s project,read:project`. |
68 | | -2. In the org → **Projects → New project → Board**, name it **"MetaObjects Roadmap"**. |
69 | | -3. Add a built-in **workflow → "Auto-add to project"** filtering `repo:metaobjectsdev/metaobjects |
70 | | - is:issue label:FR` — every `FR` issue then flows in automatically (no per-issue wiring, and new |
71 | | - FR issues self-add). |
72 | | -4. Group the board **by Milestone** (gives the Now/Next/Later release columns) and add a `Status` |
73 | | - single-select (Todo / In progress / Done) if desired. |
74 | | - |
75 | | -Because the board auto-adds by the `FR` label, the **issues are the durable record** and the board |
76 | | -is a disposable view — losing/recreating it costs nothing. |
| 37 | + If it has a spec, add one row to the **feature index** in `spec/roadmap.md` |
| 38 | + (FR | title | issue | spec) in the same change that adds the spec. The index has no status |
| 39 | + column on purpose. |
| 40 | +2. **Status or target release changes.** Change the issue (milestone, board `Status`, a comment |
| 41 | + saying what changed and why). Nothing to edit in the repo. |
| 42 | +3. **Shipping.** Close the issue with a comment naming the version and the commit or PR. Partial |
| 43 | + delivery: comment what shipped and what remains, and keep it open (or split the remainder into |
| 44 | + a new issue and close the original). |
| 45 | +4. **Cutting a release.** Every issue in the milestone is closed or moved to a later one, then the |
| 46 | + milestone is closed. `CHANGELOG.md` remains the record of what shipped. |
| 47 | +5. **When the spec and the issue disagree about status, the issue wins.** Specs are design |
| 48 | + records; they are not kept current with delivery. |
| 49 | + |
| 50 | +## The project board |
| 51 | + |
| 52 | +"MetaObjects Roadmap", owned by the `metaobjectsdev` organisation: |
| 53 | +- a built-in **Auto-add** workflow adds every issue in this repo labelled `FR`; |
| 54 | +- the default view is grouped **by milestone** (the release columns); |
| 55 | +- a `Status` single-select (Todo / In progress / Done). |
| 56 | + |
| 57 | +The board is a view over the issues, so losing or rebuilding it costs nothing. Creating or |
| 58 | +scripting it needs the token's `project` scope: `gh auth refresh -s project,read:project`. |
77 | 59 |
|
78 | 60 | ## Public roadmap (website) |
79 | 61 |
|
80 | | -A curated, adopter-facing roadmap on `metaobjects.dev/roadmap` (Now / Next / Later) is summarized |
81 | | -**from** this file — it is not a separate source of truth. Refresh it when the Release plan changes. |
| 62 | +The adopter-facing roadmap on `metaobjects.dev/roadmap` (Now / Next / Later) is summarised from |
| 63 | +the milestones: Now = the next minor's open `FR` issues, Next = the one after, Later = |
| 64 | +`1.x (later)`. Refresh it when a milestone's contents change. |
0 commit comments