Skip to content

Latest commit

 

History

History
83 lines (60 loc) · 5.85 KB

releasing.md

File metadata and controls

83 lines (60 loc) · 5.85 KB
Raw

Releasing

Steps for a new release (these are in the process of being automated):

We use release-please github action to automatically create and maintain a release PR. See the github action documentation for details.

  1. Release please will open a PR with the change log and version number updated. See open PRs

  2. If the changes look good and you are ready to perform a release approve the PR.

    • The PR for the release branch against main will look like this
      • PR title should be chore(release): <version>
      • PR should have the github label type: release.
      • Have the changelog generated by release-please in the PR description/body.
      • You can approve or Ask for approvals from stakeholders
        • It can be helpful to reviewers to provide a diff of all the files that have changed since the last release. To do this, add a compare link as a comment to the PR, or in the description/body: https://github.com/trussworks/react-uswds/compare/{previous.release.tag}...release-{new.version.number}

    image

  3. Once the release PR is approved and merged, complete the release by publishing the new version

    • release-please will tag and create a release in github automatically so the following should not be necessary. But if you can't wait it can be created manually.

      • Create a new release on Github, pointed at the merge commit of the release PR.
        • Set the tag to the version number.
        • Title your release with the version number. Use the same release notes as the release PR.
        • Point the release tag at the release merge commit by selecting Recent Commits from the Target dropdown in the Github UI. You should find the chore(release): ... commit at or near the top.

    • Download the tarball for the release from the Github Action workflow

      • After merging the release PR, a Github Actions workflow will build and package the release. You can find the action in the list by filtering for Package release actions. From the bottom of the workflow run's summary page, there is an artifacts section where the artifact can be downloaded.

      • The .tgz will be inside of the artifact.zip.

        unzip artifact.zip

        ℹ️ Archive Utility by default recursively unzips the .tgz file when unzipping the artifact.zip. If you wish to use Archive Utility instead of the terminal to unzip the artifact, disable "Keep expanding if possible" in the Archive Utility preferences.

      • Alternatively if you have the GitHub CLI tool you can grab the runid from the end of the workflow url you looked up and run the following to download the tarball.

        gh run download <runid>

    • Publish the new package to npm

      ℹ️ Publishing access is limited to package owners. If you need access and don't have it, please contact @npm-admins on Truss Slack.

      npm publish <tarball>
      • <tarball> should point to the .tgz obtained in the previous step.
      • You will be prompted for a MFA code.
      • You may need to npm login first.

      ℹ️ While it would be desireable (and is very much possible) to automate the publishing step, there are security concerns with setting up an Automation Token for npm that would mandate maintaining a strict key rotation process, which at this time exceeds the commitment that maintainers have available. To keep consumers of React USWDS secure, this step remains manual.

  4. Publish storybook

    • Manually run the Deploy Storybook Github Action from the tag that release-please newly created.

HELP

Expand this section for instructions to make last minute bugfix
  • For small bugfix, add commits on top of the existing release PR. Squash and merge the PR as usual.
  • For significant bugfix you will need to redo the release process locally and redo your PR. Reset your local release branch, add bugfix commits (use conventional commits syntax). Rerun `yarn release`. The release chore commit should be the last commit on the branch. This way, the fix will be included in the changelog as a distinct commit. Rebase and merge the PR in this special case, so that the bugfix is maintained in the commit history.
Expand this section for manual publishing steps in the event CI is down.
  • Ensure your working tree is clean - Make sure there are no changes to your working directory and that no files are staged for commit. Be sure to remove any untracked files from your working directory as well.
  • Fetch latest tag list - git fetch --all --tags
  • Checkout the new release tag - git checkout 1.1.0 (replacing 1.1.0 with your tag)
  • Rebuild app from scratch - remove node_modules and run yarn, yarn build. If any errors occur, stop here.
  • Publish the new package to npm - npm publish.

Resources