Standards metadata
- ID:
workflow.release - Role:
workflow - Level:
MUST - Applies when: A change ships or publishes an artifact, changes a published version promise, or prepares consumer-visible release information.
- Does not apply when: A coordinated internal change is neither shipped independently nor part of a published contract.
- Requires:
core,workflow.verification,topic.contracts - Specializes:
none - Verification: Release decision fixtures, ownership checks, and affected release acceptance claims.
- Canonical owner:
workflows/release.md
Select this workflow when at least one release fact is present:
- an artifact or package will be shipped or published;
- independently deployed consumers rely on a published version promise;
- a public contract, supported persisted state, or distribution channel changes; or
- consumer-visible release information must be prepared.
An internal coordinated replacement does not require release compatibility, versioning, or changelog work merely because the repository has versions. If the release facts are unknown, report an unresolved release diagnostic instead of assuming a public or internal boundary.
Classify affected contracts through Contract Evolution before choosing a version, compatibility window, deprecation, or migration.
internal-coordinatedchanges replace all owned consumers atomically and do not create a compatibility version by default.public-versionedchanges follow the published version promise.distributed-independentchanges define negotiation, overlap, migration, or typed rejection for unsupported versions.persistedchanges name supported source states and migration evidence.
When a project adopts Semantic Versioning, choose the bump from observable published-contract effects: incompatible change, compatible capability, or compatible correction. Do not infer compatibility from source syntax, commit type, or additive shape alone.
Major version zero denotes initial development under SemVer; it is not a
prerelease identifier and does not erase explicit consumer or migration
promises. Prerelease identifiers such as -alpha.1 separately describe release
precedence.
Define the release unit from actual publication and consumer ownership. Packages may version independently or in lockstep. Do not force workspace-wide version alignment without an adopted release-unit contract.
A deprecation policy exists only for a published promise that requires overlap. It states:
- the deprecated behavior and supported replacement;
- the versions or time window in which both remain supported;
- how consumers discover the deprecation;
- the removal version or decision trigger; and
- evidence for the replacement and removal path.
Breaking public or persisted changes provide migration instructions proportional to consumer needs. Internal coordinated replacement removes the old path in the same change and must not add a speculative deprecation shim.
Record consumer-visible changes for a release boundary. A project may collect entries directly under an unreleased section or use independently mergeable fragments. The chosen mechanism must avoid silent loss and merge-conflict-prone shared edits.
An entry states the observable change, affected consumers, and migration or security implications when applicable. Typical categories include added, changed, deprecated, removed, fixed, and security, but project-owned formats may differ.
Do not derive changelog inclusion solely from commit types. Internal refactors, tests, formatting, and tooling changes are omitted unless they alter the published artifact or consumer contract.
At release preparation:
- assemble all applicable entries for the selected release unit;
- resolve the version and date from the accepted version decision;
- link required migration instructions and public diagnostics;
- exclude sensitive security details until disclosure is authorized; and
- verify that the released entries match the artifact and published contract.
Define the shipped artifact set from the selected release unit, distribution channels, supported targets, and consumer contract. For each artifact, record:
- identity, version or immutable revision, target, format, and architecture;
- how consumers install, load, or execute it;
- its relationship to other artifacts in the same release;
- required integrity, authenticity, provenance, and dependency metadata; and
- the acceptance claim that proves the published artifact is usable.
Ship only artifacts that the project promises to distribute. Source archives generated by a hosting service, native packages, installers, binaries, shared libraries, debug symbols, checksums, signatures, provenance, and bills of materials are separate decisions. Do not make one artifact type universal because it was useful for another product.
Artifact names must be unique within their distribution channel and identify the facts consumers need to select the correct download. Prefer the ecosystem's native target and package conventions. Do not impose one cross-ecosystem filename template when a registry or installer owns identity and selection.
For a native artifact, derive its package coordinate or filename, prefix, extension, target and architecture labels, and relationship to companion artifacts from the release unit, ecosystem, and distribution-channel contract. An operating-system name alone does not select these facts.
Give affected consumers the authoritative acquisition location and the information required to verify, install or provision, and load the artifact, including required native dependencies and its relationship to the canonical loading contract. Place this information on the publication or package surface selected by the consumer contract; do not attach installation prose to every platform-specific implementation.
Return an unresolved artifact-plan diagnostic for missing or contradictory identity, target, acquisition, installation, loading, or evidence facts. Do not guess a conventional filename, use an ambient package as identity, substitute another artifact, or publish with incomplete consumer information.
When a release exposes language bindings, classify each applicable item before building the artifact plan:
- the product's native implementation artifact, when it is shipped separately;
- internal adapter, wrapper, generator, schema, or build input that produces a boundary but is not automatically a published product;
- generated host source or a host-language package consumed by applications; and
- a selected bundle that intentionally contains more than one of these items.
Record which items are release artifacts and which remain internal inputs. For each shipped item, apply the complete artifact plan and its own applicable contract classes. Derive artifact count, target coverage, separate or bundled composition, identity, naming, relationships, acquisition, installation/loading information, and evidence from the release unit, channels, supported targets, package ecosystems, and consumer contracts.
An adapter or generator framework is not the product identity unless the product contract says the framework itself is the product. Shared build provenance may establish consistency between related artifacts, but compatibility and version relationships remain Contracts-owned decisions.
Return an unresolved artifact-plan diagnostic when required roles, composition, identities, relationships, consumer information, or evidence are missing or contradictory. Do not assume one native library per target, separate host packages, a convenience bundle, framework-derived names, example archive names, or default success. Do not publish an internal build input merely because it participates in binding generation.
When the accepted release artifact plan includes generated bindings, derive a procedure from that plan rather than from a language profile example. The procedure must identify the Contracts-selected generation authority, generator capability and version, build and dependency inputs, target and consumer claims, output artifacts, reproducibility controls, and evidence connecting each output to its accepted input. Commands are selected only after those facts and their owner are accepted.
Do not infer a procedure from a compiled native library, source annotation,
framework default, target-language list, package name, output directory, or
globally installed tool. Do not switch generators, hand-edit generated output,
silently regenerate missing inputs, or claim success when a required toolchain,
authority, target, output, or evidence fact is unavailable. Return a typed release-procedure diagnostic for missing capability and a typed invalid
outcome for contradictory ownership or derivation.
Select integrity and supply-chain metadata from actual requirements:
- provide cryptographic checksums when consumers or the distribution channel use them to verify downloaded bytes;
- provide signatures or provenance when authenticity or build-origin claims are part of the release contract; and
- provide an SBOM when shipped content bundles dependencies or when consumer, security, regulatory, or organizational policy requires one.
Use a documented machine-readable format accepted by the intended consumer or channel. Generate metadata from the final artifact set and verify that it describes the published bytes. If required artifact or metadata facts are unknown, report an unresolved artifact-plan diagnostic instead of assuming a default package set.
State the reproducibility claim precisely. A pinned toolchain or lockfile improves input control but does not by itself prove byte-for-byte reproducible artifacts. A reproducible-build claim names the controlled inputs, build environment, comparison method, and observed evidence.
Pin toolchains, build images, generators, and dependency inputs to the extent required by the release claim. Control timestamps, host paths, locale, ordering, randomness, network access, and other nondeterministic inputs that affect the artifact.
Lockfile ownership follows the released dependency-resolution contract:
- commit a lockfile when it is source input for the resolved dependency closure used to build, test, package, or operate a released artifact;
- omit a lockfile from a published package only when the ecosystem contract intentionally delegates resolution to each consumer and the repository does not need that lockfile for its own released artifacts or tooling; and
- evaluate mixed workspaces as release units rather than applying one application-versus-library label to every member.
Do not silently regenerate missing pinned inputs during release. If the required resolution or toolchain cannot be reproduced, block the corresponding artifact claim with a typed diagnostic.
A release pipeline turns one authenticated release decision into the artifact plan and evidence required for publication. It does not infer a release from an ordinary branch push, path match, version-like string, or provider default.
Define an unambiguous dispatch contract:
- the accepted release unit and version or immutable source revision;
- who or what may authorize dispatch;
- how the pipeline distinguishes normal validation from release work;
- required claims and artifact-plan inputs; and
- the publication environment and permissions that may be reached.
The dispatch may use a protected tag, signed reference, manually approved candidate, or registry-native mechanism. The mechanism is project-owned, but an unauthenticated or ambiguous reference must produce a typed release-dispatch diagnostic and must not enter packaging, signing, or publication stages.
Derive each build procedure from the accepted artifact plan, including the artifact identity, purpose, target, mode or optimization claim, source and dependency inputs, toolchain capability, output location, and required evidence. Execute only procedures selected for required artifacts. A project with no build artifact has no build procedure; it does not gain a successful no-op build action.
Development, optimized, debug, release, native, generated, and packaged outputs are distinct only when the artifact and consumer contracts require those distinctions. Do not invent universal build action names, paired modes, commands, target binaries, or optimization meanings. When a toolchain can produce multiple outputs, select the exact planned artifact rather than guessing its default target.
Return typed invalid for contradictory artifact or mode facts and typed
release-procedure or unavailable when a required artifact, toolchain
capability, target, input, procedure, or evidence cannot be resolved. Do not
compile implicitly through another action, substitute a development artifact,
choose an alternate target or mode, or report success for an inapplicable or
unresolved build.
Build and package every target required by the accepted artifact plan. The matrix follows supported target and environment claims rather than a universal platform list. Unsupported or best-effort targets remain explicit and cannot silently satisfy required matrix entries.
Collect artifacts by planned identity. Missing, duplicate, stale, or unexpected required artifacts fail collection with diagnostics; automation must not ignore a missing required output. Generate selected integrity, provenance, signature, and dependency metadata from the final collected set, then verify it against those bytes.
The publication handoff runs only after:
- every required build, behavior, and release-artifact claim is satisfied;
- the collected set matches the artifact plan;
- version, changelog, migration, and disclosure decisions are accepted; and
- the destination and authorization are explicit.
Use least-privilege credentials scoped to the publication stage and target. Untrusted change validation must not receive release credentials. Prefer a staging or draft state when the channel supports review, but do not treat a provider-specific draft feature as universal policy.
Pipeline completion proves only the claims it records. A successful automation job cannot replace missing behavior or user-workflow evidence.
When a change selects maintenance channels, publication presentation, or release recovery procedures, follow Maintenance And Channels.
When a change selects maintenance channels, publication presentation, or release recovery procedures, follow Publication Presentation.
Use Standards Router to select every applicable language, application, boundary, and topic profile in addition to this workflow. Profiles add ecosystem mechanisms and verification but cannot override the cross-language release contracts owned here. For example, a Rust-owned release change selects the Rust profile, which routes current specialized Cargo release guidance during migration; the generic workflow does not link directly to one language's tools.
Derive the release procedure from the accepted release decisions:
- Confirm the release unit, affected contracts, consumers, and responsible authorities.
- Select applicable profiles and topics through the router.
- Accept version, changelog, migration, maintenance, channel, artifact, and publication decisions.
- Satisfy every required behavior, environment, and release-artifact claim.
- Authorize pipeline dispatch from the accepted immutable source.
- Collect and verify the exact artifact set and selected metadata.
- Project accepted notes, disclosures, artifacts, and channel state to the publication destination.
- Verify representative published artifacts when required by the acceptance plan, then record the publication result and any remaining obligations.
Commit messages, branch names, tags, registry commands, audit tools, review states, and publication commands are project- and profile-owned mechanisms. They are required only when selected by the accepted procedure. If a required step has no resolved owner or mechanism, return a typed release-procedure diagnostic rather than substituting a conventional command.
When a change selects maintenance channels, publication presentation, or release recovery procedures, follow Recovery And Withdrawal.
Before publishing, identify every claim required by the release:
release-artifactclaims for packaging, installation, loading, checksums, signatures, or publication properties;- behavior claims for changed contracts, systems, or user workflows; and
- environment qualifications for supported targets or required infrastructure.
The Verification Workflow owns claim meaning and evidence sufficiency. An artifact startup smoke proves only its named artifact assertions; it does not prove changed feature behavior, other target artifacts, or a user workflow.
Unsatisfied required claims remain visible release blockers. Release procedure and publication gates consume accepted claims but cannot downgrade or replace them.
The non-normative Release Recipe illustrates one changelog automation configuration. It does not select tools, commit categories, release mechanisms, or policy.