Release Policy

This policy defines the public release channels, verification evidence, promotion rules, and recovery responsibilities for easyeda-mcp-pro. It is authoritative for npm, GitHub Releases, the EasyEDA extension asset, GHCR, the MCP Registry, and the published documentation.

Ownership

The release manager is @oaslananka. The release manager owns channel selection, evidence review, publication, rollback, npm dist-tags, GitHub Release classification, GHCR moving tags, and post-release verification. Security-sensitive releases also follow the incident ownership in SECURITY.md and docs/REPOSITORY_GOVERNANCE.md.

No release is approved only because a version tag exists. The evidence and channel rules below are release blockers.

Release channels and identifiers

Channel	Version	Git tag	GitHub Release	npm	GHCR	MCP Registry
Stable	X.Y.Z	easyeda-mcp-pro-vX.Y.Z	non-prerelease	npm dist-tag latest	exact version, X.Y, and latest	publish
Prerelease	X.Y.Z-rc.N, where N ≥ 1	easyeda-mcp-pro-vX.Y.Z-rc.N	prerelease	npm dist-tag next	exact version and moving tag next	do not publish

Release Please is stable-only. release-please-config.json keeps prerelease: false; merging its release PR creates the reviewed stable release commit, while the separate Publish Release workflow creates the immutable tag and GitHub Release only after publication gates pass. Prereleases use the manual workflow path and must never move npm latest, GHCR latest, or the stable MCP Registry entry.

Other prerelease identifiers such as alpha, beta, or an unnumbered rc are not supported. Increment N whenever candidate code, dependencies, generated artifacts, or release metadata changes.

Candidate and promotion requirements

Stable promotion has no time-based waiting period. Once the exact source commit has the required review, CI/security results, release evidence, and applicable live EasyEDA validation, publication may proceed immediately.

• Minor and major stable releases require at least one numbered rc.N prerelease so the exact candidate can be validated before promotion.
• A narrow, reversible patch may publish without a separate release candidate when it does not touch a compatibility-sensitive path.
• A release that changes the EasyEDA bridge, transport, authentication, transaction/rollback behavior, installer/setup path, save/export behavior, or any confirmed write path requires an rc.N and live validation even when the SemVer bump would otherwise be a patch.
• Any code or runtime-dependency change after the final candidate requires a new rc.N so release evidence remains bound to the code that will actually ship.
• Stable promotion may change only version, changelog, release notes, and promotion metadata after the final candidate. Behavioral changes require another candidate.

Required release evidence

The release PR, or the public issue/PR supplied to a manual workflow dispatch, must record:

1. the exact source commit and intended tag;
2. channel, SemVer rationale, candidate identity, and promotion decision;
3. passing CI, CodeQL, Semgrep, dependency audit/review, Sonar quality gate, and Codecov changed-code status;
4. server and extension test totals, coverage summary, build results, and extension size-budget results;
5. Docker startup smoke evidence;
6. SBOM, npm provenance, artifact-attestation, portable Sigstore bundle and in-toto provenance asset, and extension checksum expectations;
7. documentation and compatibility-matrix changes;
8. the named release manager and a rollback owner;
9. known limitations, deferred failures, and the exact recovery version to restore if promotion fails.

A manual workflow dispatch must provide an evidence_url pointing to a public issue or pull request in this repository. The workflow rejects tags, channels, package versions, draft releases, or GitHub prerelease classifications that disagree.

Live EasyEDA validation

Live EasyEDA Pro validation is mandatory for bridge-loader changes, dispatcher or native API changes, write/mutation paths, transaction and rollback behavior, save/export behavior, connection lifecycle, installer/setup changes, and support-matrix changes.

Evidence must identify the exact EasyEDA Pro version and operating system, the extension package checksum, the exercised smoke scenarios, read-back/cleanup results, and any restored project state. Use a disposable project unless the validation plan explicitly proves restoration. The versioned compatibility matrix in docs/reference/easyeda-compatibility.md must be current before stable promotion.

Release-blocking automation

Stable promotion has no clock-based gate. The required PR checks and Publish Release workflow instead fail closed on source identity, channel/version consistency, commit-bound EasyEDA compatibility evidence, quality/security gates, and publication integrity. A passing candidate can therefore move directly to publication without weakening any non-time-based control.

Every stable and prerelease publication reruns the supported Node.js/pnpm preflight, dependency audit and peer checks, formatting, server and extension typechecks, lint, tool metadata/coverage validation, server tests and coverage, extension tests and coverage, generated-tool documentation drift checks, documentation build, server/extension builds, extension distribution verification, and extension size budgets.

The workflow then produces the CycloneDX SBOM, GitHub build attestations, and a tag-bound portable Sigstore bundle and in-toto provenance asset, verifies the GitHub Release channel, publishes npm with provenance to the channel-specific dist-tag, uploads the extension, SBOM, <tag>.provenance.sigstore.json, and <tag>.intoto.jsonl, and publishes channel-safe GHCR tags. MCP Registry publication runs only for stable releases.

A failed required step blocks publication. A transient rerun is allowed only when the source tag and evidence are unchanged and the original workflow run already contained every currently mandatory release gate; otherwise publish a new candidate or patch version. If a mandatory gate was added after an earlier failed run, maintainers must not re-run a pre-gate workflow attempt. Use the current workflow definition from main against the exact audited source and public evidence through the documented missing stable release identity recovery path. Recovery never waives a current executable gate.

Stable release procedure

1. Confirm the required release evidence and applicable live-validation evidence is complete.
2. Review the Release Please PR and verify that only the expected version, changelog, and release metadata changed.
3. Confirm every required PR check and bot/agent review thread is resolved.
4. Merge the Release Please PR. Do not create the stable tag manually in the normal path.
5. Verify npm latest, the non-prerelease GitHub Release, exact and moving GHCR tags, the extension/SBOM assets, provenance/attestations, MCP Registry status, and deployed documentation.
6. Publish the final evidence comment before closing the release-tracking issue.

Prerelease procedure

1. Open a candidate PR that sets every release-managed version to X.Y.Z-rc.N, updates release notes, and includes the required evidence link.
2. Merge only after the candidate PR gates pass. Create and push the annotated tag easyeda-mcp-pro-vX.Y.Z-rc.N for that exact commit.
3. Create a GitHub Release marked prerelease, not draft, for the same tag.
4. Dispatch .github/workflows/publish-release.yml with the tag, release_channel=prerelease, and the public evidence_url.
5. Verify npm next, GHCR next, exact-version artifacts, SBOM, provenance, attestations, and documentation. Confirm npm/GHCR latest did not move and the MCP Registry was not published.
6. Record the final prerelease verification evidence after all checks and registry verifications pass.

Emergency patch

An Emergency patch path is reserved for an active security incident, a broken stable installation, data-loss risk, or a release-system outage that prevents normal recovery. It does not skip executable automated gates or required live EasyEDA validation.

The public evidence issue must state the incident, customer impact, urgency, the exact known-good rollback target, the release manager, and the follow-up owner. Use a normal stable SemVer patch, not an untracked build suffix. Record a follow-up review within two business days and create a new issue for every deferred non-automated follow-up.

Rollback and yanking

Do not delete provenance evidence or silently replace immutable version artifacts.

• Move npm latest or next back to the last verified version as appropriate.
• Deprecate the affected npm version with an actionable message rather than relying on unpublish as the recovery mechanism.
• Mark the GitHub Release prominently with the incident and known-good replacement; retain the tag, SBOM, checksums, and attestations for auditability.
• Move GHCR latest or next back to the verified image digest. Exact version tags remain immutable evidence.
• For a stable MCP Registry problem, stop promotion claims, record the registry state in the incident, and follow the registry's supported correction process.
• Publish a forward-fix version as soon as it passes the applicable emergency or normal policy.

A rollback is complete only after npm, GitHub Releases, GHCR, documentation, and any stable MCP Registry claim agree on the recommended version.

Deprecation and breaking changes

Public MCP tool names, schemas, bridge protocol fields, environment variables, configuration keys, CLI behavior, and documented installation paths require a deprecation notice before removal.

• Use a major SemVer release for breaking stable behavior, even before v1.0 when practical; never hide a breaking change inside an ordinary patch.
• Announce deprecation in the changelog, release notes, migration documentation, and runtime warning where feasible.
• Keep the deprecated path for at least one minor release and 30 days before removal.
• Security or correctness risks may shorten the notice period, but the release evidence must explain the risk, migration, and accelerated timeline.
• Major releases require a numbered candidate, migration guide, rollback plan, and live validation for every affected EasyEDA path.

Documentation consistency

docs/RELEASE_PROCESS.md describes the mechanics, docs/RELEASE_VERIFICATION.md describes artifact verification, and docs/release-ci-runbook.md describes operational recovery. CONTRIBUTING.md links contributors to this policy. When workflow behavior changes, update all four documents and the repository-policy tests in the same pull request.