Skip to content

Latest commit

 

History

History
204 lines (146 loc) · 7.87 KB

RELEASE.md

File metadata and controls

204 lines (146 loc) · 7.87 KB

Releasing the Web Design Standards

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

Table of contents

  1. Principles
  2. Versioning
    1. What is a release?
    2. The public API
  3. Release process
    1. Git(/Hub) workflow
    2. Pre-releases
  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, release of the Web Design Standards 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 Standards consist 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.

  • When publishing a new release:

    1. Branch off develop and use the branch name format release-{version}, e.g.

      git fetch origin
git checkout -b release-1.0.0 origin/develop

    2. Run npm version with --no-tag to increment the version number semantically. (Versions are tagged on the master branch.)

      • For minor and major versions, publish a pre-release:

        npm version prerelease --no-tag

      • Otherwise, run either npm version minor --no-tag or npm version major --no-tag

      • In either case, npm version will increment the version number in package.json and commit the changes to git.

    3. Open a pull request from your release- branch to merge into master. List the key changes for a release in the pull request description. (The diff will show you exactly what has changed since the previous release.) See the v1.0.0 pull request for an example.

    4. Tag the release on the master branch or create the tag when you draft the release notes.

    5. Merge the release commits back into develop from master with a pull request.

    6. Write the release notes on GitHub:

      1. Draft the release from the corresponding tag on the master branch.

      2. Have at least one team member review the release notes.

      3. Publish the release on GitHub.

    7. Update the docs site with the new version number and release notes:

      1. Update the uswds Node dependency to the new version, e.g.:

        cd path/to/web-design-standards-docs
export VERSION=1.0.0
git fetch origin
git checkout -b release-${VERSION} origin/develop
npm install --save-dev uswds@${VERSION}

      2. Update the version variable in _config.yml.

      3. Follow the above release process to merge the changes to master via a pull request on the docs repo, minus the GitHub release notes.

Pre-releases

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:

  1. Create a new branch from the release branch (release-X.Y.Z) with an additional pre-release identifier, such as release-1.1.0-pre, release-1.1.0-alpha, release-1.1.0-rc1.

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

    • Publish to npm with a dist-tag, e.g.

      npm version 1.1.0-pre
npm publish --tag dev

    • Mark the GitHub release as a "pre-release", and 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 of any new issues within the prescribed testing period.

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

  4. Otherwise, proceed with the next versioned release!

Questions?

If you need help or have any questions, please reach out to us: