Skip to content

Commit 3441c31

Browse files
lalver1lalver1
authored
Docs: making a release (#56)
2 parents ffcb783 + 59f4a0f commit 3441c31

File tree

6 files changed

+275
-0
lines changed

6 files changed

+275
-0
lines changed

Diff for: ‎.github/ISSUE_TEMPLATE/release.yml

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
name: New Release
2+
description: Publish a new release of the PeMS app
3+
title: Make a Release
4+
labels:
5+
- release
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
## Prepare a new release
11+
12+
Use the form below to prepare a new release of the PeMS app.
13+
14+
Each release is coordinated by a **Release Manager**. The release manager may assign sub-tasks or ask for help
15+
as-needed, but is otherwise responsible for all aspects of the release.
16+
17+
Each release also identifies a **Smoke Tester** responsible for carrying out Smoke Tests.
18+
19+
After this issue is created, use the checklist to manage the steps
20+
of the release process, marking items as completed. [Read more about the
21+
release process](https://compilerla.github.io/pems/deployment/release/).
22+
23+
Close this issue when the checklist is complete.
24+
validations:
25+
required: true
26+
- type: input
27+
id: manager
28+
attributes:
29+
label: Release manager
30+
description: GitHub handle of who is responsible for this release; assign this issue to this user
31+
placeholder: "@cal-itp-bot"
32+
validations:
33+
required: true
34+
- type: input
35+
id: smoke-tester
36+
attributes:
37+
label: Smoke tester
38+
description: GitHub handle of who is responsible for smoke testing this release
39+
placeholder: "@cal-itp-bot"
40+
validations:
41+
required: false
42+
- type: input
43+
id: version
44+
attributes:
45+
label: Release version
46+
description: Calver-formatted version for this release
47+
placeholder: YYYY.0M.R
48+
validations:
49+
required: true
50+
- type: input
51+
id: slack
52+
attributes:
53+
label: Slack thread
54+
description: Link to the Slack thread for this release
55+
placeholder: "https://slack.com/archives/ABC/XZY"
56+
validations:
57+
required: false
58+
- type: markdown
59+
attributes:
60+
value: |
61+
## Release type
62+
63+
Reference the discussion on [the release process docs](https://compilerla.github.io/pems/deployment/release/).
64+
65+
* `Regular` release: a normal release.
66+
* `Hotfix` release: a release to quickly fix something in production.
67+
* `Rollback` release: a release to restore the app to a known working state.
68+
- type: dropdown
69+
id: type
70+
attributes:
71+
label: What type of release is this?
72+
options:
73+
- "Regular"
74+
- "Hotfix"
75+
- "Rollback"
76+
validations:
77+
required: true
78+
- type: markdown
79+
attributes:
80+
value: |
81+
## Release checklist
82+
83+
After this issue is created, edit the description to keep only the checklist for the release type.
84+
- type: checkboxes
85+
id: regular-checklist
86+
attributes:
87+
label: Regular release checklist
88+
description: Complete these items in sequence as the `Regular` release progresses
89+
options:
90+
- label: Ensure the `main` branch and secrets are up to date
91+
- label: Ensure `test` secrets are up to date
92+
- label: Create an annotated release candidate tag on `main` (`git tag -a YYYY.0M.R-rcR`)
93+
- label: Push the annotated release candidate tag (`git push origin YYYY.0M.R-rcR`)
94+
- label: QA the app in test
95+
- label: Ensure `prod` secrets are up to date
96+
- label: Create an annotated release tag on `main` (`git tag -a YYYY.0M.R`)
97+
- label: Push the annotated release tag (`git push origin YYYY.0M.R`)
98+
- label: Smoke Test the app in prod
99+
- label: Confirm acceptance of Smoke Tests by adding a comment to this issue
100+
- label: Edit release notes to link back to this Release process issue
101+
- label: Edit release notes with additional context, images, animations, etc. as-needed
102+
- type: checkboxes
103+
id: hotfix-checklist
104+
attributes:
105+
label: Hotfix release checklist
106+
description: Complete these items in sequence as the `Hotfix` release progresses
107+
options:
108+
- label: Create a hotfix branch from the latest release tag on `main` (`git checkout -b hotfix YYYY.0M.R`)
109+
- label: Commit the fixes to the hotfix branch
110+
- label: Ensure `prod` secrets are up to date
111+
- label: Create an annotated tag on the hotfix branch (`git tag -a YYYY.0M.R`)
112+
- label: Push the annotated tag (`git push origin YYYY.0M.R`)
113+
- label: Smoke Test the fix in prod
114+
- label: Confirm acceptance of Smoke Tests by adding a comment to this issue
115+
- label: Edit release notes to link back to this Release process issue
116+
- label: Edit release notes with additional context, images, animations, etc. as-needed
117+
- label: Open a PR from the hotfix branch to the current state of `main`
118+
- label: Merge the PR into `main`
119+
- type: checkboxes
120+
id: rollback-checklist
121+
attributes:
122+
label: Rollback release checklist
123+
description: Complete these items in sequence as the `Rollback` release progresses
124+
options:
125+
- label: Create an annotated release tag for the rollback on the commit associated with the last known good release tag on `main` (`git tag -a YYYY.0M.R <commit-hash>`)
126+
- label: Ensure `prod` secrets are up to date
127+
- label: Push the annotated tag (`git push origin YYYY.0M.R`)
128+
- label: Smoke Test the rollback in prod
129+
- label: Confirm acceptance of Smoke Tests by adding a comment to this issue
130+
- label: Edit release notes to link back to this Release process issue
131+
- label: Edit release notes with additional context, images, animations, etc. as-needed

Diff for: ‎docs/.pages

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
nav:
22
- Home: README.md
33
- development
4+
- deployment

Diff for: ‎docs/deployment/.pages

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
nav:
2+
- release.md
3+
- hotfix.md
4+
- rollback.md

Diff for: ‎docs/deployment/hotfix.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Making a hotfix release
2+
3+
This list outlines the manual steps needed to make a hotfix release of the
4+
`pems` app.
5+
6+
If `main` contains in-progress work that is not yet ready for a release but a simple code fix
7+
is needed in production, a separate process to test the changes before deploying to production must be undertaken.
8+
This is called a hotfix release. Typically, a hotfix release involves a simple code change that can be quickly implemented, in contrast to a [rollback release](./rollback.md), which generally requires more complex code changes which take more time to implement. To coordinate the work that's required for a hotfix release, a `Release process Issue` needs to be created. The button below will help you start a new `Release process Issue` by using an Issue template.
9+
10+
[Start a new Release on Github](https://github.com/compilerla/pems/issues/new?labels=release&template=release.yml&title=Make+a+Release){ .md-button }
11+
12+
## 0. Create a temporary hotfix branch from the latest release tag
13+
14+
```bash
15+
git checkout -b <hotfix-branch> <release-tag>
16+
```
17+
18+
Replace `<hotfix-branch>` with the hotfix branch name and `<release-tag>` with the latest release tag.
19+
20+
## 1. Fix whatever issue is wrong using the hotfix branch
21+
22+
Commit the code changes that fix the issue that prompted the hotfix.
23+
24+
## 2. Tag the HEAD of the hotfix branch with a release tag
25+
26+
```bash
27+
git tag -a YYYY.0M.R
28+
```
29+
30+
Git will open your default text editor and prompt you for the tag annotation. For the tag annotation,
31+
use the release tag version and close the text editor.
32+
33+
## 3. Push the tag to GitHub to kick off the hotfix
34+
35+
```bash
36+
git push origin YYYY.0M.R
37+
```
38+
39+
## 4. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
40+
41+
Edit release notes with additional context, images, animations, etc. as-needed and link to the `Release process Issue`.
42+
43+
## 5. Merge into `main` for the next release
44+
45+
Create a PR to merge the changes from the hotfix branch into `main` for the next release.

Diff for: ‎docs/deployment/release.md

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Making a release
2+
3+
This list outlines the manual steps needed to make a new release of the
4+
`pems` app.
5+
6+
A release is made by pushing an annotated [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) that is named after the version number for the app and the release. The name of the tag must use the version number format mentioned below. Pushing an annotated tag kicks off a deployment (implemented as a GitHub Actions workflow) that builds, tags, and pushes the app's image to the GitHub Container Registry and then creates a GitHub release. It is often useful to monitor the release process by looking at the [status of the Deploy workflow](https://github.com/compilerla/pems/actions/workflows/deploy.yml) under the `Actions` section of the repository.
7+
8+
The list of releases can be found on the [repository's Releases page](https://github.com/compilerla/pems/releases)
9+
on GitHub.
10+
11+
## 0. Decide on the new version number and create a `Release process Issue`
12+
13+
A new release implies a new version.
14+
15+
`pems` uses the [CalVer](https://calver.org/) versioning scheme, where
16+
version numbers look like: `YYYY.0M.R`
17+
18+
- `YYYY` is the 4-digit year of the release; e.g. `2024`, `2025`
19+
- `0M` is the 2-digit, 0-padded month of the release; e.g. `02` is February, `12`
20+
is December.
21+
- `R` is the 1-based release counter for the given year and month;
22+
e.g. `1` for the first release of the month, `2` for the second, and so on.
23+
24+
Version numbers for release candidates append `-rcR`, where `R` is the 1-based release counter for the anticipated release. For example, the first release candidate for the `2025.01.1` release would be `2025.01.1-rc1`.
25+
26+
To coordinate the work that's required for a release, a `Release process Issue` needs to be created. The button below will help you start a new `Release process Issue` by using an Issue template.
27+
28+
[Start a new Release on Github](https://github.com/compilerla/pems/issues/new?labels=release&template=release.yml&title=Make+a+Release){ .md-button }
29+
30+
## 1. Create a release candidate tag on `main` and push it
31+
32+
```bash
33+
git fetch
34+
git checkout main
35+
git reset --hard origin/main
36+
git tag -a YYYY.0M.R-rcR
37+
```
38+
39+
Git will open your default text editor and prompt you for the tag annotation. For the tag annotation, use `Release candidate R for YYYY.0M.R`. For example, `Release candidate 2 for 2025.01.1` would be the annotation for the second release candidate of the first release of January 2025. Finally, after closing the text editor:
40+
41+
```bash
42+
git push origin YYYY.0M.R-rcR
43+
```
44+
45+
This builds a new package, tags it, and pushes the app's image to GitHub Container Registry. No GitHub release is created for release candidates.
46+
47+
## 2. Create a release tag on `main` and push it
48+
49+
```bash
50+
git fetch
51+
git checkout main
52+
git reset --hard origin/main
53+
git tag -a YYYY.0M.R
54+
```
55+
56+
Git will open your default text editor and prompt you for the tag annotation. For the tag annotation, use the title of the Release process issue that kicked off the release. Finally, after closing the text editor:
57+
58+
```bash
59+
git push origin YYYY.0M.R
60+
```
61+
62+
This builds the package, tags it, pushes the app's image to GitHub Container Registry, and creates a GitHub release.
63+
64+
## 3. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
65+
66+
Edit release notes with additional context, images, animations, etc. as-needed and link to the `Release process Issue`.

Diff for: ‎docs/deployment/rollback.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Making a rollback release
2+
3+
This list outlines the manual steps needed to make a rollback of the
4+
`pems` app.
5+
6+
If a change is deployed to the app that makes it fail to start, making a rollback
7+
will deploy the app to a known working state again. To coordinate the work that's required for a rollback release, a `Release process Issue` needs to be created. The button below will help you start a new `Release process Issue` by using an Issue template.
8+
9+
[Start a new Release on Github](https://github.com/compilerla/pems/issues/new?labels=release&template=release.yml&title=Make+a+Release){ .md-button }
10+
11+
## 0. Create a release tag on the commit associated with the last known good release tag
12+
13+
```bash
14+
git tag -a YYYY.0M.R <commit-hash>
15+
```
16+
17+
Replace `YYYY.0M.R` with the rollback version and `<commit-hash>` with the hash of the commit associated with the last known good release tag. Git will open your default text editor and prompt you for the tag annotation. For the tag annotation,
18+
use the version of the release tag for the rollback and close the text editor.
19+
20+
## 1. Push the tag to GitHub to kick off the rollback
21+
22+
```bash
23+
git push origin YYYY.0M.R
24+
```
25+
26+
## 2. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
27+
28+
Edit release notes with additional context, images, animations, etc. as-needed and link to the `Release process Issue`.

0 commit comments

Comments
 (0)