docs(guide): document milestone-based release tracking (YYYY-MM / Next / Backlog)

Add a Milestones section to processes.gitea-issues: releases are tracked by per-repo
YYYY-MM milestones (not labels), Next = milestone with no due date, Backlog = no
milestone. Note the retired Release/* labels, cross-repo rollup via issues/search, and
assignment API. Cross-link from processes.release for release scoping.
This commit is contained in:
2026-07-02 18:25:35 -04:00
parent 30375cf5ce
commit be2c162d11
2 changed files with 27 additions and 0 deletions
@@ -21,6 +21,29 @@ already exist (avoid duplicates).
- **Workflow:** `Verify Fix` (fix deployed, verify before closing) · `Reopen` (regressed) · - **Workflow:** `Verify Fix` (fix deployed, verify before closing) · `Reopen` (regressed) ·
`Tested/Not Fixed` `Tested/Not Fixed`
> **Release is tracked by milestone, not by label.** Do **not** create `Release/*` labels — an
> earlier attempt was retired in favour of milestones (see below).
## Milestones — which release an issue ships in
A Gitea **milestone** marks the target release for an issue. Milestones (not labels) are the
release-planning mechanism: one issue = one milestone (releases are mutually exclusive), and each
milestone gives a due date + automatic burndown (open/closed %).
- **Naming:** calendar `YYYY-MM` for a dated release — e.g. **`2026-07`**, due the last day of the
month. This makes it obvious when work ships.
- **`Next`** — a milestone with **no due date**: staged for the next release, date TBD.
- **Backlog** — simply **no milestone assigned**. Don't create a "Backlog" milestone.
**Gitea milestones are per-repo** (there is no org-level milestone). So:
- Create the milestone in a repo the **first time** a matching issue is assigned there
(on-demand — avoids empty milestones cluttering repos with no work for that release).
- For a **cross-repo rollup** of everything in a release, query the search API:
`GET /repos/issues/search?state=open&milestones=2026-07&owner=hiveiq-src`.
**Assigning:** `PATCH /repos/hiveiq-src/<repo>/issues/<n>` with `{"milestone": <milestone_id>}`
(the numeric id from the repo's milestone, not the title). Every fix we work gets assigned to its
target release milestone.
## Assignment ## Assignment
- **New issue** → assign `hiveiq` (triage / fix owner). - **New issue** → assign `hiveiq` (triage / fix owner).
- **Fix deployed** → reassign to the verifier and apply **`Verify Fix`**. - **Fix deployed** → reassign to the verifier and apply **`Verify Fix`**.
@@ -9,6 +9,10 @@ audience: bcos
How we cut and ship releases. **BCOS admin only.** Golden order: **bcos.dev first → verify → PR to How we cut and ship releases. **BCOS admin only.** Golden order: **bcos.dev first → verify → PR to
`main` → production.** Never skip staging. `main` → production.** Never skip staging.
**What's in a release** is scoped by its **`YYYY-MM` milestone** (e.g. `2026-07`) — see the
Milestones section in [[processes.gitea-issues]]. Roll up everything targeted at a release with
`GET /repos/issues/search?milestones=2026-07&owner=hiveiq-src`.
## Microservice release ## Microservice release
1. Merge to `main` via the [[processes.main]] gate. 1. Merge to `main` via the [[processes.main]] gate.
2. Build + push: `./build.sh --registry registry.bcos.cloud --push` (image `hiveiq-<svc>`). 2. Build + push: `./build.sh --registry registry.bcos.cloud --push` (image `hiveiq-<svc>`).