Repository navigation
Release operations
This is the operator reference for the current USWDS release workflows. It covers manual handoffs and recovery until the remaining automation in uswds/uswds#6924 is implemented. The workflows are the source of truth for executable behavior:
Use the USWDS Release Prep workflow on an approved release branch based on
develop, with the intended patch, minor, major, or prerelease input. The workflow
rejects main and develop. Check that the intended version has a notification
entry in packages/uswds-core/src/styles/_notifications.scss.
Preparation bumps the version in its temporary checkout, builds the package, checks the compiled CSS and tarball hash, scans dependencies, and uploads a versioned tarball and hash artifact. It does not publish, commit, or push. Read the run's job summary and download its artifact before continuing.
A successful run is evidence about that exact artifact. It does not show that its generated version and hash changes have reached the release branch. The current artifact contains the tarball and hash file, not a ready-to-merge commit. Reconcile the package and lockfile versions, notification entry, and reviewed hash with the release PR before authorizing publication.
The current summary still describes manual release PR and draft-release steps from checklist 3.8 through 3.15. Keep the artifact, its SHA-256, dependency scan results, compatibility notes, and reviewer decisions together in the release PR. Use the exact reviewed tarball for the GitHub release attachment.
Pushing a matching v*.*.* tag triggers publication. The publish workflow finds
an unexpired artifact named uswds-<version>-release, downloads it, checks its
hash against the security file at the tagged commit, and publishes that tarball.
It publishes the downloaded tarball without repacking it. The workflow currently selects the newest artifact with
that name, so confirm the selected run belongs to the reviewed release.
After publication, verify the package version and distribution tag in the npm registry, then reconcile the GitHub release and development branch through the normal reviewed process. Preparation alone does not complete those steps.
| Failure | Operator action |
|---|---|
| Preparation ran on the wrong branch | Select the approved release branch and intended release type. Do not change the protected-branch guard. |
| Version, code, or dependencies changed after preparation | Prepare the updated release again and re-review its artifact and hash. Account for the workflow's version bump so the next run does not advance an already-updated version unintentionally. |
| Missing notification entry | Add the intended version's notification through the release PR, then prepare and review the updated artifact. |
| CSS, hash, or dependency check failed | Inspect the failing step and fix its cause before continuing. A partial job summary or an audit command error is not evidence of a clean scan. |
| Publication cannot find the artifact | Confirm the version, run, artifact name, and expiry. Preparation artifacts are retained for 30 days. A replacement artifact must be prepared and reviewed before publication. |
| Downloaded tarball does not match the committed hash | Stop publication. Compare the selected preparation run, reviewed tarball, tagged commit, and security file. Do not replace the hash merely to accept different bytes. |
| Publication stopped after the npm step may have run | Check whether that exact version already exists in the registry before retrying. If it exists, verify the published result and finish outstanding metadata work; do not republish or move the release tag. |
| Prerelease distribution channel is unclear | Confirm the intended channel before tagging. The current publish command has no explicit --tag, so a prerelease input alone does not establish a separate npm distribution channel. |
When escalating an exception, record the run URL, release version, source commit, artifact ID, expected hash, observed result, and remaining action. Keep tokens out of logs and release notes. Updating this page does not authorize a release.
Update this page when a workflow changes a handoff, artifact format, recovery step, or publication trigger. Remove manual instructions once their replacement is implemented and verified. Do not preserve a manual checklist merely because it existed before the release automation.
Issue #6812 tracks this documentation. The older release process page retains historical context; use this page and the workflows for current operations.