c04b7afdb9
Kanban: every open issue and pull request and what closed in the last seven days, placed in To do, In progress, In review and Done by the rules of Kira's work board, each card with its roadmap item (its roadmap:<id> label or the item linking it) and a filter by item. Journal: every release with its changes grouped by roadmap item, the merges no release has yet, and a weekly summary from roadmap/journal/<year>-<week>.md. The same journal is /hub/journal.json, for Kira's #updates and posts elsewhere: each entry names the roadmap items it moved and shipped, with their 240-character text. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
5.6 KiB
Markdown
80 lines
5.6 KiB
Markdown
# The roadmap
|
|
|
|
`roadmap.toml` is the one source of the roadmap. `tools/roadmap.py build` turns it into
|
|
[ROADMAP.md](../ROADMAP.md); the website's hub (playhorizon.dev/hub) and Kira read the same items. The work
|
|
board stays the task-level view (every issue and pull request); the roadmap is the overview, and each pull
|
|
request carries the `roadmap:<id>` label of the item it moves.
|
|
|
|
## An item
|
|
|
|
```toml
|
|
[[item]]
|
|
id = "server-dialogs" # lowercase words joined by dashes; never renamed (votes and links use it)
|
|
title = "Server dialogs and login screens"
|
|
status = "now" # now | next | later | help-wanted | shipped
|
|
area = "servers" # one of the [[area]] ids, listed in the order of priority
|
|
focus = true # optional: one of the 3 to 5 Now items in the overview
|
|
ongoing = true # optional: a workstream that goes on after its pull requests merge
|
|
plain = """Servers that show dialogs ... will work in Horizon.""" # players' words, at most 240 characters
|
|
dev = """26.3's dialog packets and model (#1720), ...""" # crates, approach, what is left
|
|
links = ["#1720", "#1734", "docs/hosting.md"] # #N, a repository path, or https://
|
|
shipped_in = "v0.2.58" # shipped items only: a game tag, launcher@x.y.z, or "website"
|
|
post = "..." # optional: the announcement when it ships, if `plain` doesn't read as one
|
|
announce = true # optional: when it ships, Kira also posts it on X (`post`, else `plain`)
|
|
```
|
|
|
|
- **No dates, ever**: Now, Next, Later. The check rejects month names, years, quarters and "next week".
|
|
"Coming soon" is the only phrase for something waiting on someone else (Microsoft sign-in, CurseForge).
|
|
- **Only what is decided.** Ideas stay in issues and in the suggestion queue until they are.
|
|
- **Only what is true in a release** for shipped items: a merged pull request isn't shipped until a release has it.
|
|
- `plain` is for players: what they will be able to do, not how. `dev` is for contributors: the code, the
|
|
vanilla classes, the pull requests, what is left. Both stay public: no machines, accounts or private notes.
|
|
- Help wanted items are good first contributions: a clear vanilla behaviour, an issue with steps, a place to
|
|
start in `dev`.
|
|
|
|
## Keeping it current
|
|
|
|
Whoever moves the work (the orchestrator on each heartbeat, or anyone in their pull request):
|
|
|
|
1. `python3 tools/roadmap.py sync`: every item whose linked pull requests all went out in a release, whose
|
|
linked issues are all closed and that isn't `ongoing` becomes `shipped`, with that release in
|
|
`shipped_in`, on top of the shipped items. It rewrites `roadmap.toml` and ROADMAP.md; open a pull request
|
|
with the change (`skip-release`).
|
|
2. `python3 tools/roadmap.py check`: the file's rules, then GitHub's state of every link. It fails when a
|
|
link is not an issue or pull request, when a Now item has no open pull request and none merged in the last
|
|
14 days (link the new work, or move it to Next or Later), and when every link of a Help wanted item is
|
|
closed. It also says which items `sync` will ship once a release has them.
|
|
3. When work starts, opens a pull request or is decided: add or move the item, add its links, then
|
|
`python3 tools/roadmap.py build`. Keep the overview's focus to the 3 to 5 biggest Now items.
|
|
4. `python3 tools/roadmap.py labels` (after the change merges): creates a `roadmap:<id>` label for each new
|
|
item, updates their colour (by status) and description, and adds the label to the open pull requests an item
|
|
links. Label a new pull request for an item by hand or by linking it and running `labels` again. Labels of
|
|
removed items are listed, never deleted.
|
|
5. Once a week, write the week's summary in `roadmap/journal/<year>-<ISO week>.md` (for example
|
|
`2026-43.md`): `# Title`, a paragraph or two for players, then `## Technical` and the same week for
|
|
contributors, with its pull requests. `build` puts it into website/data/roadmap.json; the hub's Journal tab
|
|
shows it among the releases, and `/hub/journal.json` carries it to Kira's #updates and to posts elsewhere.
|
|
6. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an
|
|
item in a normal pull request; none is published automatically.
|
|
|
|
CI runs `tests/test_roadmap.py` (in the Python tests), which fails when ROADMAP.md is not what `build` writes
|
|
or when the file breaks a rule; `python3 tools/roadmap.py check --offline` runs the same rules without GitHub.
|
|
|
|
## The journal
|
|
|
|
The hub's Journal tab and `https://playhorizon.dev/hub/journal.json` are built with each deploy of the website
|
|
(`website/src/hub.js`, `journalFrom`): every game and launcher release with its notes' changes, each placed under
|
|
the roadmap item it moves (the pull request's `roadmap:<id>` label, else the item that links it); the merged pull
|
|
requests no release has yet; and the weekly summaries above. Its JSON, newest first:
|
|
|
|
```json
|
|
{ "format": "horizon-journal", "version": 1, "generated": "…", "url": "https://playhorizon.dev/hub#journal",
|
|
"entries": [ { "id": "v0.2.57", "kind": "release | launcher | merged | week", "date": "…", "title": "…",
|
|
"plain": "one line for players", "url": "…", "dev": "weeks only",
|
|
"changes": [ { "section": "new | fixed | merged", "text": "…", "prs": [1787], "item": "discord-presence" } ],
|
|
"items": [ { "id", "title", "plain", "post" } ], // roadmap items the entry moved
|
|
"shipped": [ { "id", "title", "plain", "post" } ] } ] } // items that shipped in this release
|
|
```
|
|
|
|
`post` is at most 240 characters, ready to announce as is. Readers should remember the ids they have posted.
|