releasing.md

Releasing

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

1. Check out main and make sure you have pulled down the latest changes and tags

   git checkout main
   git pull --tags
   

2. Determine the version number of the new release

   yarn release --dry-run
   

   You should see output similar to ✔ bumping version in package.json from {old.version.number} to {new.version.number}. Take note of the {new.version.number} which will be used throughout the remainder of release process.

   ℹ️ yarn release uses standard-version which, combined with adherence to conventional commits enforced on main via title linting and using squash and merge. --dry-run logs all of the output and lets you know what standard-version would do (without actually making changes) so that you can verify that everything aligns with your expectations. Most importantly, the log will explain how the version number would be bumped, based on new commits to main.

3. Create a release branch for the new version to be released, where {new.version.number} might be 2.4.1, for example.

   git checkout -b release-{new.version.number} 
   

4. On the newly created release branch, allow standard-version to create the release

   yarn release
   

   Without using --dry-run, standard-version will commit the following changes with the message chore(release): {new.version.number}:

   • Bump the version in package.json
   • Generate a new entry in CHANGELOG.md with the version, release notes, and today's date.

5. Push the changes to Github

   git push -u origin release-{new.version.number}
   

6. Open a PR for the release branch against main

   • PR title should be chore(release): <version>
   • PR should have the github label type: release.
   • Paste the the changelog generated by standard-version in the PR description/body.
   • Ask for approvals from stakeholders, perform testing on applications, etc.
     • 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}

   

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

   • 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 tarbell 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.

   • 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.

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.