Skip to content

releasing.md

Latest commit

 

History

History
96 lines (62 loc) · 6.09 KB

releasing.md

File metadata and controls

96 lines (62 loc) · 6.09 KB
Raw

Releasing React USWDS

To make a version of the React USWDS component library available to consumers, it must be published to npm.

Table of Contents

Supporting tools

A combination of tools work in concert to automate much of the release process.

conventional-commits

Combined with our "squash and merge" preference on Pull Requests, each merged Pull Request results in a singular commit that can be parsed into our changelog.

release-please

Create and manage release PRs when releasable changes have been merged to main, based on our release-please configuration.

The primary purpose of release PRs is to update the changelog and increment the version number in package.json.

Merging a release-please release PR will automatically create a tag/release in GitHub.

github-actions

The following custom actions support the release pipeline:

npm

Publish and host versioned build artifacts for the community to download as a project dependency.

Release and Publish React USWDS

Prerequisites

To perform a release, a maintainer must first

Additionally, at least one releasable change must have been merged to main since the previous release.

Note

If there are no releasable changes as defined by the release-please configuration, there will be no Release PR to start the release process with.

Step-by-step

Follow these steps to create and publish a release for a given version, <major.minor.incremental>.

  1. Review and merge the current release PR.

    • Ensure the branch is up to date with main.
    • PR CI checks will likely be stuck in a pending state on the release PR requiring administrator override to merge. This is because GitHub actions in a workflow run cannot trigger new workflow runs. Since release-please creates and updates the release PR via a workflow action, PR checks will not run under normal circumstances. We consider this acceptable since release PRs do not change code.

  2. Wait for release-please to create the corresponding tag in GitHub including the updates from the changelog.

  3. Find and wait for the corresponding package-release.yml action to complete.

  4. From the successful package-release workflow run, download the build artifact from the Artifacts section of the build summary: Where to find the build artifact for download

  5. Get the tarball (trussworks-react-uswds-<major.minor.incremental>.tgz) by unzipping the downloaded artifact.zip

    unzip artifact.zip
    • If, instead of the terminal, you wish to use Archive Utility to unzip arifact.zip be aware that Archive Utility defaults to recursively unzipping files, including the .tgz itself when unzipping the artifact.zip. You will first need to disable the "Keep expanding if possible" setting in your Archive Utility preferences.

  6. Publish the tarball (trussworks-react-uswds-<major.minor.incremental>.tgz) to npm by running the following command and following the prompts in your terminal.

    npm publish trussworks-react-uswds-<major.minor.incremental>.tgz

  7. Notify our #g-uswds and #g-uswds-public Slack channels about the release.

Warning

If any automations are not working for any reason but a release needs to go out before triaging and fixing them, you will have to emulate the corresponding steps manually.

The automations are composed to avoid common "gotchas" so take care at each step to emulate exactly the outputs of previous automation runs.

Fix a Broken Release

If a release is fundamentally broken for all consumers, the followings steps are recommended to resolve:

  1. Triage and fix the issue via the normal bug fix Pull Request process.
  2. Publish a new release following the normal release steps.
  3. Deprecate the broken version in npm so that consumers know to upgrade