Release Process - usds/us-forms-system GitHub Wiki

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

This project follows semantic versioning 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?

The code for each release "lives" in two different places:

  1. On GitHub as a tag and corresponding release
  2. On npm as a release of the us-forms-system package with the same version number as the GitHub release

The public API

The U.S. Forms System contains both code and styles that create forms, define their look, and affect their behavior. As such, clients do not expect the look or behavior of their existing forms to change on patch releases, or on feature releases that only add new functionality. A patch release should incorporate changes that the team agrees affect truly negative behavior that users of the project would consider to be bugs (as opposed to undocumented features). Examples of changes that trigger a major version increment include:

  • Changing the default styling for an element
  • Changing the default UI rendering or validation for data types
  • Changing names or behavior of existing properties in the schema

In many cases, semver-major updates to dependencies such as USWDS or react-jsonschema-form will also trigger the need for a semver-major update in this project as well.

Release process

Git workflow

  • We have two main branches that are never deleted:

    • master always points to the most recent approved updates, some of which have not been officially released
    • production contains releases

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

    1. Branch off master:

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

    2. Name your branch anything except master or production. If there is a related issue, a good rule is to use the issue number and then follow with a keyword or two: 154-readme-docs

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

Publishing a new release

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

Create the release branch

  • Determine if the version is a patch (#.#.#), minor (#.#.0), or major (#.0.0) version based on the semver rules described above.
  • Branch off master and use the branch name format release-{{ version }}.
git pull origin
git checkout -b release-{{ version }} origin/master
  • When there is further work on master after branching, determine whether those changes should be merged 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. You will need publish access to the us-forms-system npm repository. 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 us-forms-system@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

  • Ensure you're on the right branch! (e.g. release-{{ version }})
  • Use the npm version command to increment the package.json version number and commit the changes.
  • 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 production

  • Push the version branch up to GitHub
  • Open a pull request from your release branch into production with the title "Release {{ version }}."
  • List the key changes in the release in the pull request description.
  • 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 production.

Check that the release was successful

If the CircleCI process fails, see the CircleCI configuration details wiki page.

Create the release in GitHub

  • Check out the production branch locally and git pull upstream production.
  • View the package.json file and ensure the version listed is the one just released.
  • Run npm pack to build the assets zip file. It will be created at us-forms-system-{{ version }}.tgz. Do not add this file to the repo.
  • In GitHub releases select Draft a new release
  • Add the tag: v{{ version }}
  • Use target: production
  • Add release notes to the body
  • Have at least one team member review the release notes
  • Attach the tgz binary you just created
  • Select Publish release

Merge production back into master

  • Ensure that the master branch is using the latest version and has the production commits

Update the docs/sample repo with the new version number on a new branch

TODO since we don't have a docs/sample repo using the latest branch

  • In theus-forms-system-site repo, create a branch off master
git fetch origin
git checkout -b use-{{ version }} origin/master
  • Change the us-forms-system dependency in package.json to the new version from npm
npm install --save-exact us-forms-system@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.

Check the us-forms-system download page to assure correctness

  • (TK, there is currently no download page) Ensure the file downloads properly and is the right version.

Publicize the release

  • (TK, we have no specific publicity plans right now)

Setup the next draft release notes

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