Skip to content

Component release management

Jump to bottom
Joseph Castle edited this page Jan 12, 2021 · 14 revisions

This is our official process for releasing new versions of @code.gov/* components:

code-gov-front-end consumes the cautious package through npm. If cautious is updated between releases of code-gov-front-end it must also be released, published to npm, and updated in the package.json of code-gov-front-end before deploying and publishing a new version of code-gov-front-end.

Table of Contents

  1. Testing
  2. Versioning
  3. Release process
    1. Git workflow
    2. Publishing a new release

Testing

These components are meant to be used with the code-gov-front-end project. Please follow the configuration settings for that project.

Link package to test components locally

To test component changes on your local machine follow these steps to do so (examples uses the code-gov-style repo but this should be replaced with whichever component you are testing):

  1. Clone the latest version of the code-gov-style repository.
  2. Run npm install to install the dependencies required for the package in the code-gov-style directory.
  3. Run npm link in the root level of the code-gov-style directory on your local machine.
  4. On the code-gov-front-end project, clone the repository and run npm install if you haven’t done this already.
  5. Run npm link @code.gov/code-gov-style in the root level of the code-gov-front-end directory on your local machine. Look for sim link icon (@) in front-end @code-gov node_modules.

Versioning

See Version Control for more information about semantic versioning and what constitutes a release

Release process

Git workflow

See Git Workflow for more information about how to create new branches and suggest changes to @code.gov/* repositories

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 the semantic version - patch (#.#.#), minor (#.#.0), major (#.0.0). (Note: Patch refers to bug fixes and dependency updates, Minor refers to feature changes or enhancements, and Major refers to changes that may cause a break in dependency in someone else's program.)

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

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

Example > git checkout -b release-0.0.7 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. See the npm publish documentation for additional options.

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

This bumps the version number in package.json and commits that change. It should echo back the new version number to your terminal command line. git log should show that new commit.

Publish the release to npm

  • Push the version branch up to GitHub
  • Merge release-{{ version }} back in to the master branch
  • Run git checkout master and git pull origin master to update your local repository
  • Run npm publish to release the package to the npm directory
  • Check that the new release was published to npm

If you get the following error then run npm login to authenticate to npm.

 npm ERR! publish Failed PUT 401  
 npm ERR! code E401  
 npm ERR! You must be logged in to publish packages.

Create the release in GitHub

  • On the releases page for the repository on GitHub.com, select the release draft notes you had previously started or Draft a new release
  • Add the tag: v{{ version }}
  • Use target: master
  • For any release of code-gov-style or major releases of another component, add release notes to the body and have at least one team member review the release notes
  • Select Publish release This will publish the release on GitHub and display the release notes page. Leave this window open while you go to the next steps.

Update the code-gov-front-end to use this component version

You will next need to enter a Pull Request on code-gov-front-end to use this new version of the component you just released.

  • Create a new branch of code-gov-front-end following our Git Workflow
  • Open the package.json of code-gov-front-end
  • Update the version number of the package(s) you just published to npm and GitHub
  • Run npm install to update the package-lock.json file.
  • Commit the changes and make a PR to master to update code-gov-front-end before the next deployment of the front end. In this PR, link to the component release notes.
  • Add this PR title to the latest draft release notes for the front-end.
Clone this wiki locally