Home

code-gov-style-guide release process

This is our official process for releasing new versions.

Table of contents

1. Principles
2. Versioning
   1. What is a release?
3. Release process
   1. Publishing a new release

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 Code.gov core front-end code "lives" in 2 places:

1. GitHub as a tag and corresponding release
2. On npm as a release of the code-gov-front-end package with the same version number as the GitHub release

Release process

Git workflow

• We have two main branches that are never deleted:
  • master contains changes being prepped for a release, is always deployable
  • dev used for testing and review of new features
• 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 pretty much anything except master, federalist-, or with the release- or hotfix- prefix. Suggested prefixes include refactor-, feature-, docs-, issue#, and patch-.

  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 ⚠️

Before you get started

• Close all running processes in the terminal.

Create the release branch

• Determine if the version is a patch (#.#.#), minor (#.#.0), or major (#.0.0) version

• Branch off master and use the branch name format release-{{ version }}

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

---

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.

---

Deploy the release

• Push the version branch up to GitHub
• Wait for the deployment success message in your terminal
• Check that Federalist deployed the new release's site
• Merge release-{{ version }} back in to the master branch

---

Publish the release

• Run 'npm publish' to release the package to the npm directory
• Check that the new release was published to npm

---

Create the release in GitHub

• In GitHub releases select the release draft notes you had previously started or 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
• Select Publish release

---

Publicize the release

• Post a message in the #code-gov-partners Slack channel linking to the release. Pin the message to the channel.
• Post a message to the code@gsa.gov listserv.

---

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

---