Skip to content

release-engineering: adopt SemVer tags and document release policy #5

@commitconfirm

Description

@commitconfirm

Parent

Part of #3 (umbrella: end-user update path for v1.0).

Summary

MNM currently delivers updates via implicit tracking of main.
Adopt SemVer release tags so end users can pin to known-stable
releases instead of bleeding-edge main.

Proposed scheme

  • SemVer: vMAJOR.MINOR.PATCH (e.g., v1.0.0, v1.0.1, v1.1.0)
  • MAJOR: breaking changes to data layer, API surface, or required
    configuration. None expected in the v1.x lifecycle.
  • MINOR: new features, new collectors, new UI surfaces, new
    required environment variables (with defaults that preserve
    existing behavior).
  • PATCH: bug fixes, doc updates, dependency bumps that don't
    change behavior.
  • Pre-release suffix: v1.1.0-rc.1 for release candidates if/when
    needed. Not required for v1.0.0.

Release process (initial draft — refine during implementation)

  1. Confirm main is green (all checks pass, manual smoke test
    against lab devices clean).
  2. Update CHANGELOG.md with the release section (move "Unreleased"
    entries under the new version heading).
  3. Bump any version strings in code/config (TBD: identify where these
    live — likely docker-compose.yml image labels, FastAPI app
    version, etc.).
  4. Commit the version bump.
  5. Tag: git tag -a v1.0.0 -m "Release v1.0.0".
  6. Push commit + tag: git push origin main --follow-tags.
  7. Create GitHub release from the tag, paste the CHANGELOG section
    as release notes.

Cadence

Event-driven for v1.0.x patch releases (cut a release when meaningful
fixes accumulate or when a security/bug fix needs prompt delivery).
Reassess for v1.1+.

Tag v1.0.0

Once this issue's process is in place, tag the first official
release. v1.0.0 should be the commit where all three umbrella
sub-issues are closed and the project is genuinely ready for outside
users.

Acceptance criteria

  • Versioning policy documented in .claude/CLAUDE.md (Key Design
    Decisions Log)
  • Release process documented in docs/RELEASING.md (or similar —
    maintainer-facing, not end-user-facing)
  • First tag (v1.0.0 or v0.x.0 if maintainer prefers a slower
    ramp) cut from main
  • GitHub release created from the tag with CHANGELOG-derived notes
  • UPGRADE.md (sub-issue A) updated to reference tagged releases as
    the recommended end-user pin

Open questions for maintainer

  • Start at v1.0.0 or v0.x.0? Recommendation: v1.0.0 once
    all three umbrella sub-issues are closed. The "Block C polling
    stable, modular collectors clean, audit-verified" state warrants
    it. Alternative: cut v0.9.0 now to exercise the release process
    without committing to v1.0 semantics.
  • Should tags trigger anything (CI, release notes generation, etc.)
    for v1.0?
    Recommendation: no — keep the process manual for v1.0
    to avoid premature automation. Revisit post-v1.0.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestrelease-engineeringRelease process, tagging, versioning, update flowv1.0-blockerBlocks v1.0 release

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions