Skip to content

feat(release): add immutable SemVer publication lane - #25

Merged
offendingcommit merged 4 commits into
mainfrom
feat/plugin-kit-semver-releases
Aug 14, 2026
Merged

feat(release): add immutable SemVer publication lane#25
offendingcommit merged 4 commits into
mainfrom
feat/plugin-kit-semver-releases

Conversation

@offendingcommit

@offendingcommit offendingcommit commented Aug 14, 2026

Copy link
Copy Markdown
Owner

Summary

Begins the compatible plugin-kit rollout by turning reviewed conventional commits into one tested, immutable release identity. This PR delivers the release boundary only; consumer SemVer migrations and fleet qualification/promotion remain follow-on work. It can merge without Hermes upstream changes, and publication stays disarmed until the external registry and repository controls are configured.

Session-settled decisions carried from planning: published SemVer releases are the promotion boundary, and conventional commits determine release intent.

Design

  • Materializes the version, changelog commit, and tag locally before testing. The exact source is bundled before any test code runs.
  • Runs unit/public contracts, the real upstream Hermes contract, and the single artifact build in separate fresh jobs. Mutable Hermes code cannot alter the packaged source.
  • Builds the wheel and sdist once. A prepublication manifest binds source SHA, test evidence, filenames, sizes, and SHA-256 values.
  • Uses one Just interface for local development, CI, agent guidance, and release receipts. Each isolated CI job installs the immutable Just 1.58.0 setup action before invoking a recipe.
  • Publishes through PyPI Trusted Publishing, re-downloads and verifies both registry files, then finalizes the receipt with their direct files.pythonhosted.org URLs.
  • Creates the GitHub Release only after PyPI verification and requires GitHub immutable releases. Patch and minor receipts are qualification candidates; major receipts require migration approval.
  • Uses a dedicated, repository-scoped GitHub App for the atomic main/tag handoff. Remote-ref checks make an acknowledged-but-interrupted push safe to resume.

Activation boundary

The workflow is intentionally inert unless SEMANTIC_RELEASE_ENABLED=true. Before enabling it, operators must configure and validate:

  • reviewed immutable v0.7.0 baseline tag;
  • PyPI pending Trusted Publisher and protected pypi environment;
  • GitHub immutable releases;
  • protected source-promotion environment with the dedicated App credentials;
  • main ruleset whose only source-promotion bypass actor is that App;
  • isolated Trusted Publishing and ambiguous-push recovery exercises.

This PR does not create those controls, publish a package, push a tag, or create a release.

Validation

  • just test: 153 passed, 12 expected runtime-contract skips.
  • just test-release: 35 release intent, artifact identity, task-runner, and workflow contracts passed.
  • just test-contract: 11 passed against upstream Hermes 1169fb50a4cdfbac62463d0e8bd9766fedcd4189.
  • just test-context-engine-contract: passed against the exact deployed upstream Hermes revision f80f453ae0679347e38abc917c7f94f717bf96c5.
  • just build check-dist: wheel and sdist built; both passed Twine metadata validation.
  • just --fmt --check, actionlint, yamllint, uv lock --check, py_compile, and git diff --check: passed.
  • Independent review caught and fixed external-test workspace poisoning, incomplete registry identity, actor-wide ruleset bypass, mutable Release assets, unbounded PyPI preflight, ambiguous source-push retry, a per-job Just setup blind spot, and stale agent-facing runner guidance.

Post-Deploy Monitoring & Validation

  • Watch the updated Test workflow on this PR and the first disarmed Release workflow evaluation after merge.
  • Healthy means every Just-using job installs pinned Just 1.58.0 before its recipe, all contract jobs pass, and release publication remains skipped while SEMANTIC_RELEASE_ENABLED is not true.
  • Treat setup-action download failures, missing recipes, receipt-command mismatches, or unexpected publication jobs as failures.
  • If the runner migration blocks CI, revert 39bcf15 to restore the Makefile boundary. Jonathan owns that rollback decision during the first main-branch workflow cycle.

Separate release intent from deployment identity by testing the final release commit before any source or artifact publication. Keep the lane disarmed until the registry, environment, baseline tag, and repository protections are reviewed.
Isolate mutable Hermes contract execution from the one artifact build, and finalize release receipts only from verified PyPI bytes. Dedicated App credentials and immutable-release checks keep source promotion narrow. Idempotent remote-ref validation lets an ambiguous successful push resume instead of stranding the release.
Keep one repository task interface for local development, CI, and release receipts so the validation boundary cannot drift between environments.
Carry the current upstream Hermes context-engine contract forward while preserving the Just-only CI interface.
@offendingcommit
offendingcommit merged commit 6ba5700 into main Aug 14, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant