Skip to content

Latest commit

 

History

History
204 lines (166 loc) · 12.8 KB

project-planning.md

File metadata and controls

204 lines (166 loc) · 12.8 KB

Planning and Release Workflow

Keep planning small enough to maintain. Use the roadmap for direction, milestones for release grouping, issues for outcomes, and PRs for implementation evidence.

What belongs where

Surface Question it answers What to record
Roadmap Where are we going and why? Current release focus, next candidates and explicit non-commitments
Milestone Which release should deliver this? Version, goal, acceptance, blockers and release link
Issue Which problem/outcome needs work? Benefit, reason for priority, acceptance criteria, dependencies and scope limits
Pull request How was it implemented and verified? Linked issue, implementation choices, tests, compatibility/security impact and rollout gaps
Release-readiness issue Is the integrated work actually deliverable? Exact candidate SHA, evidence, canary/upgrade results, publication and image verification
GitHub Release What was actually shipped? Published tag, user-facing changes, upgrade notes and delivery evidence

Existing GitHub Projects can remain a work view. They do not need to duplicate release notes, and a board status must not be interpreted as proof of versioned publication. This setup does not add or reorganize a Project.

A minimal working cycle

  1. Capture the reason. For substantial work, use an issue or a reviewed proposal. Write the user problem, expected benefit and acceptance before implementation. Small bug/dependency PRs do not require a duplicate issue.

  2. Select one active release scope. Create a version milestone, such as v2.5.0, with a short goal and a release-readiness issue. A proposed version is adjustable. Do not set a due date unless the maintainer actually commits to it.

  3. Assign accepted work. Attach the implementation issue and related PR to that milestone. Link them with Fixes #123 only when the PR really resolves the issue. Use Refs #123 for partial work. Keep ownership and existing useful labels explicit.

  4. Review and merge normally. Required repository checks and human review rules still apply. Record material trade-offs, validation environments and any deferred acceptance. Planning never bypasses branch protection or security gates.

  5. Validate delivery. Keep the release-readiness issue open after feature PRs merge. Check the exact candidate, required CI, native image scans, relevant real-environment acceptance and upgrade/recovery behavior. Link the evidence, not just a checkbox.

  6. Publish and verify. Set VERSION in app/version.py in the same change as the release notes; the tag build refuses a tag that differs from it. Tag the reviewed candidate, publish release notes, and verify the tag-triggered pipeline, versioned AMD64/ARM64 image and SBOM/provenance. Only then close the readiness issue and milestone; move the outcome into completed history.

    Use a lightweight tag on the merged candidate commit, not an annotated tag:

    git tag v3.2.0 <candidate-sha>
    git push origin v3.2.0
    gh release create v3.2.0 --verify-tag --notes-file docs/releases/v3.2.0.md

    GitHub shows a lightweight tag as verified when its commit is signed, which holds for merges made on GitHub. An annotated tag is an object of its own and shows as unverified unless the tag itself is signed. Releases are immutable, so a published tag cannot be replaced afterwards; v2.7.0 to v3.1.0 carry unsigned annotated tags.

Milestone progress is a count of closed work items, not effort completed or proof that a version has shipped. A nearly complete milestone with a blocked release gate is still not a published release. Issues and PRs can both represent the same outcome, so do not interpret their combined count as distinct features delivered.

Example: optional Warpgate support

#237 states the user's gateway need. #238 implements selector usernames, interactive authentication and a default-off administration gate. The request is closed and the PR merged, but neither belongs to v2.4.0 because the tag predates their merge.

The published v2.5.0 release includes that implementation and the related workspace fixes. #248 records the exact candidate, publication and image verification. The maintainer authorized publication with the reported deployment acceptance still unverified; those checks were recorded in the now-closed #254. The v2.6.0 deployment acceptance record is #288, closed with remaining environment-specific checks explicitly unverified. Publication and operational acceptance are recorded separately, without repeating implementation PRs or marking unrun checks passed.

Record decisions and blockers

Use a short dated comment on the relevant issue/PR:

Decision (YYYY-MM-DD): selected/deferred/changed <scope>.
Why: <observed problem, benefit or risk>.
Trade-off: <compatibility, security, maintenance or dependency constraint>.
Acceptance: <observable result and required environment>.
Blocker / next action: <exact dependency, owner and action>.
Evidence: <issue/PR/test run/release link and exact SHA where applicable>.

Do not make an unresolved bug disappear by removing its milestone. If work moves, record the old/new scope and reason. Security vulnerabilities still follow the private reporting process in SECURITY.md, not a new public planning issue.

Release gate checklist

Use the focused v2.5.0 readiness checklist as the first example. Future checklists should include:

  • Confirmed scope/version and explicitly deferred items.
  • Final candidate SHA and required CI/review evidence.
  • Tests matching the changed risks; separate deployment-specific checks from automated CI.
  • Upgrade, backup/restore and rollback results or explicit supported limitations.
  • Current native AMD64/ARM64 scans and immutable source/image identity.
  • Release notes, tag/release links and final versioned-image/attestation verification.

Do not close a release gate before publication or infer a final-head test from an earlier PR revision. An accepted operational limitation needs a maintainer decision; required CI/security gates cannot be silently waived. No automation or automatic merge is added.

Maintaining the history

The initial release-history manifest is a dated, reviewable snapshot of ten published releases and the proposed next scope. It includes prepared native milestone descriptions, 161 merged PR mappings and 24 verified issue links. The original backfill result is retained in the manifest. Later releases extend the history; candidate is null when no next version has been selected.

Applied on 2026-10-04: ten historical milestones are closed and the proposed v2.5.0 milestone was open at that time. The backfill assigned and verified 160 PRs, 24 implementation-linked issues and the open release gate #248 (185 items). PR #98 returned HTTP 404 through the API and signed-in browser and could not be assigned. The original 161-PR reconstruction is preserved; the manifest records the exception and native milestone numbers.

Published on 2026-10-05: v2.5.0 adds PRs #249-#252 to the original scope. The release milestone and #248 are closed after tag/image verification. The current manifest at that time contained eleven releases and 165 merged PR mappings; deferred deployment acceptance was recorded in #254 (now closed). The original backfill counts above are not rewritten.

Published on 2026-10-23: v2.6.0 adds 24 first-included PRs and three implementation-linked issues. The manifest now contains twelve releases, 189 merged PR mappings and 27 implementation-linked issues. Release record #289 and milestone 12 close after tag/image verification; the separate deployment acceptance follow-up #288 was later closed with unrun environment checks explicitly retained. PR #255 first appears in this release because membership follows Git ancestry. The original dated backfill snapshot remains unchanged.

Published on 2026-11-04: v2.7.0 adds 16 first-included PRs and one implementation-linked issue (#303 through #304). The manifest now contains thirteen releases, 205 merged PR mappings and 28 implementation-linked issues. Tag CI and native image publication passed; the release notes record immutable image identity, SBOM/provenance verification and the resolved browser CI timeout. Historical backfill snapshots remain unchanged.

Published on 2026-11-08: v3.0.0 adds 5 first-included PRs and one implementation-linked issue (#312 through #313). The manifest now contains fourteen releases, 210 merged PR mappings and 29 implementation-linked issues. Tag CI and native image publication passed; the release notes record immutable image identity and SBOM/provenance verification. Historical backfill snapshots remain unchanged.

Applied on 2026-11-14: v2.7.0 and v3.0.0 had been published without a native milestone. Milestone 13 (v2.7.0, 16 PRs and #303) and milestone 14 (v3.0.0, 5 PRs and #312) were created from the manifest mapping, verified and closed. The proposed v3.1.0 milestone holds the 17 PRs merged since v3.0.0, issues #327 and #334 and release record #338. The manifest records this in native_milestone_followups; earlier snapshots remain unchanged.

Published on 2026-11-14: v3.1.0 adds 18 first-included PRs and two implementation-linked issues (#327, #334). The manifest now contains fifteen releases, 228 merged PR mappings and 31 implementation-linked issues. Tag CI and native image publication passed; the release notes record immutable image identity and SBOM/provenance verification. Release record #338 and milestone 15 are closed.

Published on 2026-11-15: v3.2.0 adds 8 first-included PRs and no implementation-linked issues. The manifest now contains sixteen releases, 236 merged PR mappings and 31 implementation-linked issues. It was the first release tagged with a lightweight tag on the merged candidate commit. Tag CI and native image publication passed; the release notes record immutable image identity and SBOM/provenance verification. Release record #347 and milestone 16 are closed.

For historical backfill:

  1. Read all existing native milestones before creating anything; reuse matching versions and preserve their descriptions/dates unless the maintainer explicitly approves edits.
  2. Use each release's first-tagged-inclusion mapping, not a merge date or a closed issue timestamp. Do not attach unmerged/superseded PRs as delivered implementation.
  3. Assign historical work and close only milestones for actually published releases. Put the true publication date in the description. Do not invent historical due dates or rewrite commit, issue, PR or release metadata to make the plan look older.
  4. Keep the proposed next milestone open and include the release-readiness issue. Verify every write, then update native_milestone_backfill in the snapshot with the actual result/date and milestone numbers. Preserve unrelated existing assignments.

For future releases, append evidence and a released entry when publication is verified; retain historical tag membership. Update the roadmap's baseline/current section through a normal documentation PR. Check links and keep reasons concise rather than copying a commit-by-commit changelog.

Weekly review

Read the latest release/tag comparison, recent merged/open PRs, open issues, the active milestone and its readiness issue. Report:

  • Meaningful user/security/operational changes, not every commit.
  • Implemented versus published outcomes.
  • Actual blockers, owner/action and evidence gaps.
  • At most three decisions or next actions; mark recommendations as recommendations.

This allows a weekly status report to describe roadmap progress from public evidence instead of guessing from the number of commits or closed tickets.