Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add help section to releasing README #1867

Merged
merged 3 commits into from
Jan 12, 2022
Merged

docs: Add help section to releasing README #1867

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
75958f5
Add further readme edits after last release
haworku Jan 7, 2022
63115be
Cleanup for real markdown
haworku Jan 7, 2022
23ab6fc
Merge branch 'main' into hw-readme
haworku Jan 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 29 additions & 19 deletions docs/releasing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ Steps for a new release (these are in the process of being automated):
- Determine the new version based on new commit messages
- Generate a new entry in the changelog with the version, release notes, and today's date.
- Commit all of the above changes with the message `chore(release): <version>`
- Note: Creating a new tag is **skipped** (this will happen as part of the publish flow)

3. Push changes to a new branch following the naming pattern: `release-<version>`

Expand All @@ -19,31 +18,42 @@ Steps for a new release (these are in the process of being automated):

- PR title should be `chore(release): <version>`
- Ask for approvals from stakeholders, perform testing on applications, etc.
- Last minute bugfix from testing or PR feedback can be made.
- Add bugfix commits on top of the release. Squash and merge the PR as usual.
- _For significant bugfix (special case)_
- Redo the release. Reset your local release branch, add bugfix commits (use conventional commits syntax). Rerun `yarn release`. The release chore commit should be the last commit on the branch. The fix will be included in the changelog. \_Rebase and merge the PR in this special case.

![image](./release_PR.png)

5. Once the release PR is approved, complete the release and publish the new version:
- Merge the PR and create a new [**release tag**](https://github.com/trussworks/react-uswds/releases) on Github, pointed at the merge commit of the release PR. Use the same notes as release PR.
- To point the release tag at the release merge commit, select `Recent Commits` from the `Target` dropdown in the Github UI and you should find the `chore(release): ...` commit at or near the top.
- After merging the release PR, an [Actions workflow](../.github/workflows/package-release.yml) will build and package the release. From the bottom of the workflow run's summary page, [there is a section where the artifact can be downloaded](https://github.com/actions/upload-artifact#where-does-the-upload-go).
5. Once the release PR is approved and merged, complete the release by publishing the new version:
- Create a new [**release**](https://github.com/trussworks/react-uswds/releases) on Github, pointed at the merge commit of the release PR.
- Look for the `Draft a new release` button.
- Set the tag to the version number.
- Title your release with the version number. Use the same release notes as the release PR.
- Point the release tag at the release merge commit by selecting `Recent Commits` from the `Target` dropdown in the Github UI. You should find the `chore(release): ...` commit at or near the top.
- Download the tarbell for the release from the Github Action workflow
- After merging the release PR, a [Github Actions workflow](../.github/workflows/package-release.yml) will build and package the release. You can find the action in the list by looking for "Package release". From the bottom of the workflow run's summary page, there is an artifacts section [where the artifact can be downloaded](https://github.com/actions/upload-artifact#where-does-the-upload-go).
- The `.tgz` will be inside of the `artifact.zip`.
- Archive Utility by default recursively unzips the `.tgz` file when unzipping the `artifact.zip`. If you wish to change this behavior, disable "Keep expanding if possible" in the Archive Utility preferences.
- It may be easiest to use the terminal and run `unzip archive.zip`.
- It may be easiest to use the terminal and run `unzip artifact.zip`.
- [Publish](https://docs.npmjs.com/cli/v6/commands/npm-publish) the new package to npm: `npm publish <tarball>`. You will be prompted for a MFA code.
- `<tarball>` should point to the `.tgz` obtained in the previous step.
- You may need to `npm login` first.
- Publishing access is limited to package owners. If you need access and don't have it, please contact `@npm-admins` on Truss Slack.
- Note: While it would be desireable (and is very much possible) to automate the publishing step, there are security concerns with setting up an Automation Token for npm that would mandate maintaining a strict key rotation process, which at this time exceeds the commitment that maintainers have available. To keep consumers of React USWDS secure, this step remains manual.
<details>
<summary>Expand this section for manual publishing steps in the event CI is down.</summary>

- **Ensure your working tree is clean** - Make sure there are no changes to your working directory and that no files are staged for commit. Be sure to remove any untracked files from your working directory as well.
- **Fetch latest tag list** - `git fetch --all --tags`
- **Checkout the new release tag** - `git checkout 1.1.0` (replacing `1.1.0` with your tag)
- **Rebuild app from scratch** - remove `node_modules` and run `yarn`, `yarn build`. If any errors occur, stop here.
- **Publish the new package to npm** - `npm publish`.
</details>

## HELP
<details>
<summary>Expand this section for instructions to make last minute bugfix</summary>
<ul>
<li>For small bugfix, add commits on top of the existing release PR. Squash and merge the PR as usual.</li>

<li>For significant bugfix you will need to redo the release process locally and redo your PR. Reset your local release branch, add bugfix commits (use conventional commits syntax). Rerun `yarn release`. The release chore commit should be the last commit on the branch. This way, the fix will be included in the changelog as a distinct commit. <i>Rebase and merge the PR </i>in this special case, so that the bugfix is maintained in the commit history.</li>
</ul>
</details>

<details>
<summary>Expand this section for manual publishing steps in the event CI is down.</summary>

- **Ensure your working tree is clean** - Make sure there are no changes to your working directory and that no files are staged for commit. Be sure to remove any untracked files from your working directory as well.
- **Fetch latest tag list** - `git fetch --all --tags`
- **Checkout the new release tag** - `git checkout 1.1.0` (replacing `1.1.0` with your tag)
- **Rebuild app from scratch** - remove `node_modules` and run `yarn`, `yarn build`. If any errors occur, stop here.
- **Publish the new package to npm** - `npm publish`.
</details>