From a823e26c73e5a7aba1f74fd6c348b963e54ac1d5 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Wed, 24 Feb 2021 15:58:19 -0500 Subject: [PATCH 1/3] 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". --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d9328070..ecd6fce6 100644 --- a/README.md +++ b/README.md @@ -60,15 +60,21 @@ When you're ready to release a new version of the `identity-style-guide` package 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` +3. 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`. +4. 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` +5. Change the "Unreleased" heading in `CHANGELOG.md` to the version you decided in Step 3. Commit this change to your new branch. +6. 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. +7. 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? +8. If everything looks alright, continue with publishing by running `npm publish`. +9. Push your release branch to the GitHub repository and open a pull request. +10. 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. From 39fc4e0a5ae1cf30594f13a310eb39313d17e0cf Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Thu, 25 Feb 2021 08:27:18 -0500 Subject: [PATCH 2/3] Add prerequisites text describing permissions process --- README.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ecd6fce6..3bf1686e 100644 --- a/README.md +++ b/README.md @@ -58,23 +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. Decide the version number for the new release. +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 main branch on your local machine by running `git checkout main`. +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. -4. 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. +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` -5. Change the "Unreleased" heading in `CHANGELOG.md` to the version you decided in Step 3. Commit this change to your new branch. -6. 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. +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. -7. Do a trial publish by running `npm publish --dry-run`. +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. - Consider: In the files listed, are there any that should or shouldn't be included? Does the version match what you expect? -8. If everything looks alright, continue with publishing by running `npm publish`. -9. Push your release branch to the GitHub repository and open a pull request. -10. Once approved and merged, create a new release on the [GitHub "Releases" page](https://github.com/18F/identity-style-guide/releases). +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. From 2948dd895404fecb49534f17ed3d8cb7fae897c9 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Thu, 25 Feb 2021 08:28:45 -0500 Subject: [PATCH 3/3] Advise main branch pull to ensure latest changes are included --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3bf1686e..b61e8ac8 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ When you're ready to release a new version of the `identity-style-guide` package 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 main branch on your local machine by running `git checkout main`. +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.