Release process

This is our official process for releasing new versions of the U.S. Web Design System.

Note: Running these steps while in a Google Hangout can degrade performance enough to cause a test failure. If you find tests timing out, try to shut down any concurrent intensive processes.

Table of contents

1. Principles
2. Versioning
   1. What is a release?
   2. The public API
3. Release process
   1. Publishing a new release
4. Questions?

Principles

1. Follow well-established versioning practices
2. Provide detailed notes for each release
3. Encourage contributions and thank contributors for their hard work

Versioning

Semantic versioning is a method of numbering release versions that aims to help users understand the implications of upgrading from one release to another. Semantic version numbers take the form major.minor.patch, where:

• Bug fixes increment the patch number (e.g. 1.0.0 to 1.0.1)
• New features increment the minor number and reset patch (e.g. 1.0.1 to 1.1.0)
• Changes to the public API (breaking changes) increment the major version and reset minor and patch (e.g. 1.1.2 to 2.0.0)

What is a release?

Technically, the release of the Web Design System core code "lives" in two different places:

1. On GitHub as a tag and corresponding release
2. On npm as a release of the uswds package with the same version number as the GitHub release

The public API

In most software projects, the "public API" corresponds to a single set of programming constructs, such as public classes or functions. Because the USWDS consists of tightly-bound HTML, CSS, and JavaScript, we must consider any "breaking" change to any of these as a change to the public API. For example, any of the following should trigger a major version increment:

• Changing the name of any .usa- class name (documented or not)
• Changing the way in which elements with .usa- class names are structured in HTML
• Changing the HTML "API" for any of our interactive components, such as the accordion

Release process

Git workflow

• We have two main branches that are never deleted:

  • main always points to the latest release
  • develop contains changes being prepped for a release

  ⚠️ If you're updating 2x there's v2-develop and v2-main

• When introducing a change (feature, bug fix, etc.):

  1. Branch off develop:

     git fetch origin
     git checkout -b feature-foo origin/develop

  2. Name your branch pretty much anything except main, develop, or with the release- or hotfix- prefix. Suggested prefixes include refactor-, feature-, docs-, and patch-.

  3. File your pull request to merge into the develop branch.

Publishing a new release

⚠️ In these docs, {{ version }} should always be replaced with the semantic version number, i.e. 1.2.1 ⚠️

Before you get started

• Close all running USWDS processes in the terminal.
• ⚠️ Assure all references in the README and in the settings are for the proper version
• ⚠️ Make sure to update the notifications file

Create the release branch

• Determine if the version is a patch (#.#.#), minor (#.#.0), or major (#.0.0) version
• Branch off develop and use the branch name format release-{{ version }}.

git pull origin
git checkout -b release-{{ version }} origin/develop

• If there's been further work on develop since branching, merge the most recent develop into the version branch.

---

Prerelease if necessary

When releasing potentially disruptive changes, it's good practice to publish pre-releases of planned versions. These are sometimes also called release candidates. Here's how it works:

• Create a new branch from the release branch (release-{{ version }}) with -pre as an additional pre-release identifier, i.e. release-{{ version }-pre.

Follow the release process for your pre-release branch, with the following modifications:

• Publish to npm with a dist-tag npm version {{ version }}-pre npm publish --tag dev
• Mark the GitHub release as a "pre-release"
• Be sure to note how long you intend on waiting for show-stopping bug reports before proceeding with the release.
• Include instructions for installing the pre-release from npm with the dist-tag, e.g.: npm install --save uswds@dev
• Directly notify users who may be impacted by the proposed changes, and encourage them to alert us to any new issues within the prescribed testing period.

If you receive reports of any regressions (specifically, new issues introduced in the release), you can decide whether to address them in another pre-release or file them for the next official release. If you decide to move proceed with the release, it's good practice to alert users of the issue in your release notes, preferably with a ⚠️ emoji or similar.

Otherwise, proceed with the next versioned release!

---

Version the release with npm

npm version will increment the version number semantically in package.json and commit the changes to git. Versions will be tagged on the main branch.

NOTE: When releasing a v1 branch, we give it an explicit uswds-v1.x tag as part of the deploy script on Circle. Otherwise it'll get the latest tag when released.

• For prerelease releases: Run npm version prerelease --no-tag.
• For patch releases: Run npm version patch --no-tag.
• For minor releases: Run npm version minor --no-tag.
• For major releases: Run npm version major --no-tag.

---

Check ZIP and hash

Occasionally, the release script builds an incomplete ZIP file. Check the contents of the generated ZIP (in /dist) to assure it has all the necessary files. The generated hash needs to be committed to main, so the release ZIP must be built before the final commit to main.

• Check complete ZIP file against the generated hash in /security
• Assure the lib directory in scss contains only normalize.scss
• Drag the ZIP to your desktop so it can be added to the release later

---

Merge the release into main

• Push the version branch up to GitHub
• Open a pull request from your release branch into main with the title "Release {{ version }}."
• List the key changes in the release in the pull request description. See the v1.0.0 pull request for an example.
• Wait for all tests to complete successfully. (Note: CodeClimate and Circle will not run on this branch, they will only run once merged.)
• Have at least one team member approve the pull request
• Once the pull request is approved, merge it into main.

---

Check that the release was successful

• Check that the CircleCI process completes
• Check that the new release was published to npm
• Check that Federalist deployed the new release's fractal site: components.designsystem.digital.gov

---

Create the release in GitHub

• Close all running USWDS processes in the terminal
• In GitHub releases select Draft a new release
• Add the tag: v{{ version }}
• Use target: main
• Add release notes to the body
• Have at least one team member review the release notes
• Attach the zip binary you just created
• Select Publish release

---

Merge main back into develop

• Ensure that the develop branch is using the latest version
  • Note: if squashing commits, merge release-{{ version } into develop

---

Update the docs repo with the new version number and changelogs on a new branch

• In theuswds-site repo, create a branch off main

git fetch origin
git checkout -b use-{{ version }} origin/main

• Change the uswds dependency in package.json to the new version from npm

npm install --save-exact uswds@latest

• Commit this change to the release branch
• Find instances of the old release number in _config.yml and update to the new release number.
• For each release change, create a changelog item

---

Merge docs changes into the docs repo's main branch

• Push the release branch to GitHub
• Open a pull request from your release branch into main.
• List the key changes in the release in the pull request description.
• Have at least one team member approve the pull request
• Once the pull request is approved, merge it into main. This will trigger Federalist to rebuild and redeploy the production site.

---

Check the USWDS website to assure correctness

• Check that all changelogs are up-to-date
• Check that the Download code ZIP file linked from the Download code and design files page works (it should point to the ZIP file you uploaded when you released the new version on GitHub) and that the correct version number is mentioned under the link.
• Check that the new release shows up on the Release notes page.

---

Publicize the release

• Post a message in the #uswds-public Slack channel linking to the release. Pin the message to the channel.

---

Setup the next draft release notes

• Click "Draft a new release" from the Releases page
• Set the target to main
• Add the title [unreleased]
• Save draft

---

Bonus 2.0: Merge main or develop back into release-2.0

• Branch off of release-2.0 to create a branch release-2.0-use-{{ version }}
• Pull main or develop into release-2.0-use-{{ version }}
• Fix any merge conflicts
• Open a PR pointing release-2.0-use-{{ version }} to release-2.0
• Wait for all tests to complete successfully
• Have at least one team member approve the pull request
• Once the pull request is approved, merge it into release-2.0