Docs: making a release

.github/ISSUE_TEMPLATE/release.yml

@@ -0,0 +1,131 @@
+name: New Release
+description: Publish a new release of the PeMS app
+title: Make a Release
+labels:
+  - release
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Prepare a new release
+
+        Use the form below to prepare a new release of the PeMS app.
+
+        Each release is coordinated by a **Release Manager**. The release manager may assign sub-tasks or ask for help
+        as-needed, but is otherwise responsible for all aspects of the release.
+
+        Each release also identifies a **Smoke Tester** responsible for carrying out Smoke Tests.
+
+        After this issue is created, use the checklist to manage the steps
+        of the release process, marking items as completed. [Read more about the
+        release process](https://compilerla.github.io/pems/deployment/release/).
+
+        Close this issue when the checklist is complete.
+    validations:
+      required: true
+  - type: input
+    id: manager
+    attributes:
+      label: Release manager
+      description: GitHub handle of who is responsible for this release; assign this issue to this user
+      placeholder: "@cal-itp-bot"
+    validations:
+      required: true
+  - type: input
+    id: smoke-tester
+    attributes:
+      label: Smoke tester
+      description: GitHub handle of who is responsible for smoke testing this release
+      placeholder: "@cal-itp-bot"
+    validations:
+      required: false
+  - type: input
+    id: version
+    attributes:
+      label: Release version
+      description: Calver-formatted version for this release
+      placeholder: YYYY.0M.R
+    validations:
+      required: true
+  - type: input
+    id: slack
+    attributes:
+      label: Slack thread
+      description: Link to the Slack thread for this release
+      placeholder: "https://slack.com/archives/ABC/XZY"
+    validations:
+      required: false
+  - type: markdown
+    attributes:
+      value: |
+        ## Release type
+
+        Reference the discussion on [the release process docs](https://compilerla.github.io/pems/deployment/release/).
+
+        * `Regular` release: a normal release.
+        * `Hotfix` release: a release to quickly fix something in production.
+        * `Rollback` release: a release to restore the app to a known working state.
+  - type: dropdown
+    id: type
+    attributes:
+      label: What type of release is this?
+      options:
+        - "Regular"
+        - "Hotfix"
+        - "Rollback"
+    validations:
+      required: true
+  - type: markdown
+    attributes:
+      value: |
+        ## Release checklist
+
+        After this issue is created, edit the description to keep only the checklist for the release type.
+  - type: checkboxes
+    id: regular-checklist
+    attributes:
+      label: Regular release checklist
+      description: Complete these items in sequence as the `Regular` release progresses
+      options:
+        - label: Ensure the `main` branch and secrets are up to date
+        - label: Ensure `test` secrets are up to date
+        - label: Create an annotated release candidate tag on `main` (`git tag -a YYYY.0M.R-rcR`)
+        - label: Push the annotated release candidate tag (`git push origin YYYY.0M.R-rcR`)
+        - label: QA the app in test
+        - label: Ensure `prod` secrets are up to date
+        - label: Create an annotated release tag on `main` (`git tag -a YYYY.0M.R`)
+        - label: Push the annotated release tag (`git push origin YYYY.0M.R`)
+        - label: Smoke Test the app in prod
+        - label: Confirm acceptance of Smoke Tests by adding a comment to this issue
+        - label: Edit release notes to link back to this Release process issue
+        - label: Edit release notes with additional context, images, animations, etc. as-needed
+  - type: checkboxes
+    id: hotfix-checklist
+    attributes:
+      label: Hotfix release checklist
+      description: Complete these items in sequence as the `Hotfix` release progresses
+      options:
+        - label: Create a hotfix branch from the latest release tag on `main` (`git checkout -b hotfix YYYY.0M.R`)
+        - label: Commit the fixes to the hotfix branch
+        - label: Ensure `prod` secrets are up to date
+        - label: Create an annotated tag on the hotfix branch (`git tag -a YYYY.0M.R`)
+        - label: Push the annotated tag (`git push origin YYYY.0M.R`)
+        - label: Smoke Test the fix in prod
+        - label: Confirm acceptance of Smoke Tests by adding a comment to this issue
+        - label: Edit release notes to link back to this Release process issue
+        - label: Edit release notes with additional context, images, animations, etc. as-needed
+        - label: Open a PR from the hotfix branch to the current state of `main`
+        - label: Merge the PR into `main`
+  - type: checkboxes
+    id: rollback-checklist
+    attributes:
+      label: Rollback release checklist
+      description: Complete these items in sequence as the `Rollback` release progresses
+      options:
+        - 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>`)
+        - label: Ensure `prod` secrets are up to date
+        - label: Push the annotated tag (`git push origin YYYY.0M.R`)
+        - label: Smoke Test the rollback in prod
+        - label: Confirm acceptance of Smoke Tests by adding a comment to this issue
+        - label: Edit release notes to link back to this Release process issue
+        - label: Edit release notes with additional context, images, animations, etc. as-needed

docs/.pages

@@ -1,3 +1,4 @@
 nav:
   - Home: README.md
   - development
+  - deployment

docs/deployment/.pages

@@ -0,0 +1,4 @@
+nav:
+  - release.md
+  - hotfix.md
+  - rollback.md

docs/deployment/hotfix.md

@@ -0,0 +1,45 @@
+# Making a hotfix release
+
+This list outlines the manual steps needed to make a hotfix release of the
+`pems` app.
+
+If `main` contains in-progress work that is not yet ready for a release but a simple code fix
+is needed in production, a separate process to test the changes before deploying to production must be undertaken.
+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.
+
+[Start a new Release on Github](https://github.com/compilerla/pems/issues/new?labels=release&template=release.yml&title=Make+a+Release){ .md-button }
+
+## 0. Create a temporary hotfix branch from the latest release tag
+
+```bash
+git checkout -b <hotfix-branch> <release-tag>
+```
+
+Replace `<hotfix-branch>` with the hotfix branch name and `<release-tag>` with the latest release tag.
+
+## 1. Fix whatever issue is wrong using the hotfix branch
+
+Commit the code changes that fix the issue that prompted the hotfix.
+
+## 2. Tag the HEAD of the hotfix branch with a release tag
+
+```bash
+git tag -a YYYY.0M.R
+```
+
+Git will open your default text editor and prompt you for the tag annotation. For the tag annotation,
+use the release tag version and close the text editor.
+
+## 3. Push the tag to GitHub to kick off the hotfix
+
+```bash
+git push origin YYYY.0M.R
+```
+
+## 4. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
+
+Edit release notes with additional context, images, animations, etc. as-needed and link to the `Release process Issue`.
+
+## 5. Merge into `main` for the next release
+
+Create a PR to merge the changes from the hotfix branch into `main` for the next release.

docs/deployment/release.md

@@ -0,0 +1,66 @@
+# Making a release
+
+This list outlines the manual steps needed to make a new release of the
+`pems` app.
+
+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.
+
+The list of releases can be found on the [repository's Releases page](https://github.com/compilerla/pems/releases)
+on GitHub.
+
+## 0. Decide on the new version number and create a `Release process Issue`
+
+A new release implies a new version.
+
+`pems` uses the [CalVer](https://calver.org/) versioning scheme, where
+version numbers look like: `YYYY.0M.R`
+
+- `YYYY` is the 4-digit year of the release; e.g. `2024`, `2025`
+- `0M` is the 2-digit, 0-padded month of the release; e.g. `02` is February, `12`
+  is December.
+- `R` is the 1-based release counter for the given year and month;
+  e.g. `1` for the first release of the month, `2` for the second, and so on.
+
+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`.
+
+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.
+
+[Start a new Release on Github](https://github.com/compilerla/pems/issues/new?labels=release&template=release.yml&title=Make+a+Release){ .md-button }
+
+## 1. Create a release candidate tag on `main` and push it
+
+```bash
+git fetch
+git checkout main
+git reset --hard origin/main
+git tag -a YYYY.0M.R-rcR
+```
+
+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:
+
+```bash
+git push origin YYYY.0M.R-rcR
+```
+
+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.
+
+## 2. Create a release tag on `main` and push it
+
+```bash
+git fetch
+git checkout main
+git reset --hard origin/main
+git tag -a YYYY.0M.R
+```
+
+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:
+
+```bash
+git push origin YYYY.0M.R
+```
+
+This builds the package, tags it, pushes the app's image to GitHub Container Registry, and creates a GitHub release.
+
+## 3. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
+
+Edit release notes with additional context, images, animations, etc. as-needed and link to the `Release process Issue`.

docs/deployment/rollback.md

@@ -0,0 +1,28 @@
+# Making a rollback release
+
+This list outlines the manual steps needed to make a rollback of the
+`pems` app.
+
+If a change is deployed to the app that makes it fail to start, making a rollback
+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.
+
+[Start a new Release on Github](https://github.com/compilerla/pems/issues/new?labels=release&template=release.yml&title=Make+a+Release){ .md-button }
+
+## 0. Create a release tag on the commit associated with the last known good release tag
+
+```bash
+git tag -a YYYY.0M.R <commit-hash>
+```
+
+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,
+use the version of the release tag for the rollback and close the text editor.
+
+## 1. Push the tag to GitHub to kick off the rollback
+
+```bash
+git push origin YYYY.0M.R
+```
+
+## 2. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
+
+Edit release notes with additional context, images, animations, etc. as-needed and link to the `Release process Issue`.