Skip to main content
How a change travels from commit to release notes, and where its status is recorded. Short rules, so reviewers and release notes stay readable as the repo grows.

Commits

  • One clubbed commit per theme. A feature that spans API, CLI, dashboard and docs is one commit, even at 50 or more files. Do not split a feature into 1 to 3 file commits.
  • Subject: type(scope): outcome, under 72 characters. Types are feat, fix, perf, refactor, docs, test and chore. Describe the result, not the activity.
  • Body: at most 3 short lines of why. Optional trailers Task: 118, 123 and ADR: 074.
  • No AI attribution and no co-author trailers.

Pull request description

Fill in the PR template. Keep the bullets specific: name the verb, the route, the setting key, the flag, the table or the UI page. For a release PR, build the description from the merged PR sections:
  1. Group by capability, not by commit order.
  2. List every migration number, forward only.
  3. List every new runtime setting key with its default.
  4. List every flag with its status label.
  5. Collect behaviour changes and upgrade notes in one place.
  6. Collect the “Not verified / needs a real host” items so unproven checks are visible.

Where tracking lives

Update the matching row in the same commit that changes the behaviour. A claim without a row or evidence does not ship as stable.

Issues and project

Issues and PRs are public and curated. An issue exists only for a shippable feature or epic with acceptance criteria, never for scratch notes.
  • One issue per shippable feature, from the Tracked feature form. Epics use the Epic form and list child issues.
  • Each issue gets a milestone per release (for example v0.9.5) and the labels area/, type/, size/* and priority/*.
  • The commit carries an Issue: #N trailer. The PR description says Closes #N.
  • Proof for PRs and tickets is generated by scripts/proof (see Proof automation); a new page or card brings its affected.map line.
  • Project fields on the GLINR Projects board: Status, Priority (P0 to P2), Size (XS, S, M, L, XL), Product (Levelrail, Thesvg, Kelvo, Other, set from the repo name), Surface (API, CLI, Dashboard, Agent, Docs, Multi). The board is public and shared with other glincker repos, so filter by Product.
  • Helper: scripts/track.sh issue <title> <body-file> [--labels a,b] [--milestone vX] [--size XS|S|M|L|XL] [--surface API|CLI|Dashboard|Agent|Docs|Multi] creates the issue and adds it to the board. scripts/track.sh ship <issue> <sha> comments the commit. It needs gh auth refresh -s project,read:project. Set GLINR_PROJECT (default 7) and GLINR_OWNER (default glincker) to target another board.

Generated files

Regenerate, never hand merge. On a conflict in a generated file (API reference, OpenAPI, route tree, locale catalogs), take either side, then run the repo generator and commit the result.

Labels and evidence

Move a label up only with the evidence in the same change, and link the test or run in the feature-status row.

Runtime settings, not env

New tunables are runtime settings: reachable from the API, CLI and dashboard, applied live where possible. Environment variables only seed defaults and never lock a value. Thresholds are never hardcoded. Record the key, default and whether it applies live or needs a restart in the PR.

Assignment

When a PR opens, the auto-assign workflow assigns the PR author. Issues linked from the PR body (Closes, Fixes, Resolves, Tracks #N) or from Issue: #N commit trailers get the same assignee if they have none. Bots and fork PRs are skipped for issues, and human-opened issues are left to triage. Project board fields are set by the project’s own automation, not by this workflow.

Reviewing a change

A reviewer should be able to answer from the PR alone: what changed, which surfaces got it, what migrates, what is new to configure, what is unproven, and how to roll back.
Last modified on November 17, 2026