Skip to content

Latest commit

 

History

History
161 lines (115 loc) · 5.8 KB

RELEASE.md

File metadata and controls

161 lines (115 loc) · 5.8 KB
Raw

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
  3. What is a release?
  4. The public API
  5. Release process
  6. Git(/Hub) workflow
  7. 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. As a naming convention, your branch name can be anything except master, develop, or with the release- or hotfix- prefix

    3. Changes are merged back 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.

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

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

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

    4. Write the release notes on GitHub:

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

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

    7. Publish the release on GitHub.

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

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

    ```sh
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}
```

    1. Update the version variable in _config.yml.

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

Questions?

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