Skip to content

Commit

Permalink
Improve README guidance for release process (#188)
Browse files Browse the repository at this point in the history
* Improve README guidance for release process

**Why**:

- Changelog should be edited to replace "Unreleased" with the release version.
- Main branch is protected, so you cannot commit the version bump directly. Improve text to include steps for creating a branch, opening a pull request, and merging before creating a new release.
- Dry-run testing is all well and good, but there wasn't any guidance around what exactly one should be looking for in considering whether "everything looks alright".

* Add prerequisites text describing permissions process

* Advise main branch pull to ensure latest changes are included
  • Loading branch information
aduth authored Feb 25, 2021
1 parent ca8c31c commit d96515e
Showing 1 changed file with 16 additions and 9 deletions.
25 changes: 16 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,17 +58,24 @@ More information can be found in Federalist’s [How Builds Work](https://federa

When you're ready to release a new version of the `identity-style-guide` package there are just a few steps to take.

1. Make sure all the changes intended for release are merged into the `main` branch.
2. Check out the main branch on your local machine by running `git checkout main`.
3. Run `npm version` to bump the package version, passing one of `patch`, `minor`, or `major` depending on the types of changes included.
- Example: `npm version patch`
Before starting, make sure that all changes intended for release should be merged into the `main` branch. You will need permissions to publish the package to npm. Check current package owners by running `npm owner ls` or by consulting the list of admins through the [Services and Accounts handbook page](https://handbook.login.gov/articles/accounts.html). If you do not have access, contact an owner to have access granted or to publish on your behalf.

1. Check out the latest main branch on your local machine by running `git checkout main`, followed by `git pull`.
2. Decide the version number for the new release.
- The `CHANGELOG.md` should ideally include all pending changes under an "Unreleased" heading.
- This project uses [semantic versioning](https://semver.org/): breaking changes should bump the major version, backwards-compatible changes should bump the minor version, and bug fixes should bump the patch version.
- Ideally all changes to be included in this version have been described in `CHANGELOG.md` to make the choice of version obvious.
4. A new version will be created. This will update `package.json` and `package-lock.json` automatically and create a commit that should be pushed.
5. Do a trial publish by running `npm publish --dry-run`.
3. Since the main branch is protected, you will need to bump the version in a new branch and open a pull request. Start by creating a new branch.
- Example: `git checkout -b release-4-3-1`
4. Change the "Unreleased" heading in `CHANGELOG.md` to the version you decided in Step 3. Commit this change to your new branch.
5. Run `npm version` to bump the package version, passing one of `patch`, `minor`, or `major` depending on what you had decided in Step 3 for the next version.
- Example: `npm version patch`
- A new version will be created. This will update `package.json` and `package-lock.json` automatically and create a commit.
6. Do a trial publish by running `npm publish --dry-run`.
- No need to run any special build steps — the publish script will lint the source JavaScript and Sass files, and clean and re-build all assets before including them in the published package.
6. If everything looks alright, continue with publishing by running `npm publish`.
7. Create a new release on the [GitHub "Releases" page](https://github.com/18F/identity-style-guide/releases).
- Consider: In the files listed, are there any that should or shouldn't be included? Does the version match what you expect?
7. If everything looks alright, continue with publishing by running `npm publish`.
8. Push your release branch to the GitHub repository and open a pull request.
9. Once approved and merged, create a new release on the [GitHub "Releases" page](https://github.com/18F/identity-style-guide/releases).
- Use `main` as the target.
- The release version should match the version just published to `npm` (for example, `v2.1.5`).
- Use the version name as the release title.
Expand Down

0 comments on commit d96515e

Please sign in to comment.