Release process

Maya Benari edited this page Aug 6, 2018 · 33 revisions

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?


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


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:

    • master always points to the latest release
    • develop contains changes being prepped for a release
  • 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 master, 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.

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 :warning: 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 master branch.

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

Merge the release into master

  • Push the version branch up to GitHub
  • Open a pull request from your release branch into master 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.
  • Have at least one team member approve the pull request
  • Once the pull request is approved, merge it into master.

Check that the release was successful

Create the release in GitHub

  • Close all running USWDS processes in the terminal
  • In the master branch run npm run release to build the assets zip file. It will be created at dist/uswds-{{ version }}.zip.
  • In GitHub releases select Draft a new release
  • Add the tag: v{{ version }}
  • Use target: master
  • 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 master 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 on a new branch

  • In theuswds-site repo, create a branch off master
git fetch origin
git checkout -b use-{{ version }} origin/master
  • 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

Merge docs changes into the docs repo's master branch

  • Push the release branch to GitHub
  • Open a pull request from your release branch into master.
  • 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 master. This will trigger Federalist to rebuild and redeploy the production site.

Check the USWDS website to assure correctness

  • 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 master
  • Add the title [unreleased]
  • Save draft

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

  • Branch off of release-2.0 to create a branch release-2.0-use-{{ version }}
  • Pull master 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
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.