Skip to content

Commit

Permalink
Chore: update documentation and issue template due to tag-based relea…
Browse files Browse the repository at this point in the history 
…ses (#2270)
  • Loading branch information
@lalver1
lalver1 authored Aug 7, 2024
2 parents 3aa7934 + 828ce67 commit 24b5915
Show file tree
Hide file tree
Showing 7 changed files with 138 additions and 82 deletions.
45 changes: 27 additions & 18 deletions .github/ISSUE_TEMPLATE/release.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,17 +53,19 @@ body:
value: |
## Release type
Reference the diagram and discussion on [the release process docs](https://docs.calitp.org/benefits/deployment/release/).
Reference the discussion on [the release process docs](https://docs.calitp.org/benefits/deployment/release/).
* `Regular` release: propagates from `main` to `test`, and then `test` to `prod`. Only possible if `main` is ready to deploy.
* `Hotfix` release: fix is merged into `prod`. After release, fix is propagated to `main` and `test`.
* `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
Expand All @@ -79,18 +81,15 @@ body:
description: Complete these items in sequence as the `Regular` release progresses
options:
- label: Ensure the `main` branch and secrets are up to date
- label: Create a branch called release/version from the source branch
- label: Bump the application version
- label: Open a PR for the release branch into `main`, merge
- label: Ensure `test` secrets are up to date
- label: Open another PR from `main` to `test`, merge
- 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: Open a PR for the `test` branch into `prod`, merge
- 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: Tag the release on the `prod` branch, push the tag to GitHub (see [docs](https://docs.calitp.org/benefits/deployment/release/#5-tag-the-release) for commands)
- label: Create a release in GitHub for the tag, generating release notes
- 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
Expand All @@ -99,17 +98,27 @@ body:
label: Hotfix release checklist
description: Complete these items in sequence as the `Hotfix` release progresses
options:
- label: Make the hotfix in a branch from `prod`
- label: Bump the application version
- 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: Open a PR from the hotfix branch into `prod`, merge
- 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: Tag the release on `prod`, push the tag to GitHub (see [docs](https://docs.calitp.org/benefits/deployment/release/#5-tag-the-release) for commands)
- label: Create a release in GitHub for the tag, generating release notes
- 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: Create a branch off `main`
- label: Open a PR from `prod` into that branch, merge
- label: (optional) Adapt hotfix to current state of `main` in that same branch
- 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
2 changes: 2 additions & 0 deletions docs/deployment/.pages
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,7 @@ nav:
- infrastructure.md
- secrets.md
- release.md
- hotfix.md
- rollback.md
- troubleshooting.md
- workflows.md
45 changes: 45 additions & 0 deletions docs/deployment/hotfix.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Making a hotfix release

This list outlines the manual steps needed to make a hotfix release of the
`benefits` 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.

[Start a new Release on Github](https://github.com/cal-itp/benefits/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.
83 changes: 25 additions & 58 deletions docs/deployment/release.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
# Making a release
# Making a regular release

This list outlines the manual steps needed to make a new release of the
`benefits` app.

A release is made by merging changes into the `prod` branch, which kicks off a
deployment to the production environment. More details on the deployment steps
A release is made by pushing an annotated tag. The name of the tag must use
the version number format mentioned below. This kicks off a deployment to the
production environment and creates a GitHub release. The version number for the
app and the release will be the tag’s name. More details on the deployment steps
can be found under [Workflows](./workflows.md).

The list of releases can be found on the [repository Releases page](https://github.com/cal-itp/benefits/tags)
Expand All @@ -25,77 +27,42 @@ version numbers look like: `YYYY.0M.R`
- `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.

## 1. Prepare release in a branch
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 `2024.01.1` release would be `2024.01.1-rc1`.

Typically changes for a release will move from `main`, to `test`, to `prod`. This
assumes `main` is in a state that it can be deployed without disruption. (This is called a `Regular` release.)
## 1. Create a release candidate tag on `main` and push it

If `main` or `test` contain in-progress work that is not ready for production,
and a hotfix is needed in production, a separate process to test the changes
before deploying to `prod` must be undertaken. (This is called a `Hotfix` release.)

As implied in the previous step, all releases follow the same version number format.

The following diagram shows how a release should propagate to `prod` under
different circumstances:

```mermaid
graph LR
A(Release branch) --> B{Are main and test ready to deploy?};
B -->|Yes| C(main);
C --> D(test);
D --> E(prod);
B -->|No| E;
```bash
git fetch
git checkout main
git reset --hard origin/main
git tag -a YYYY.0M.R-rcR
```

By convention the release branch is called `release/YYYY.0M.R` using the
upcoming version number.

## 2. Bump the application version number

The app code maintains a version number in
[`benefits/__init__.py`](https://github.com/cal-itp/benefits/blob/main/benefits/__init__.py),
used by the instrumentation and logging systems.

This version number must be updated to match the new version in the same format:
`YYYY.0M.R`

## 3. Open a PR

Initially from the release branch to the target environment branch, following
the merge sequence in the diagram above.
Git will open your default text editor and prompt you for the tag annotation. For the tag annotation, use the release candidate version. Finally, after closing the text editor:

## 4. Merge the PR

After checks pass and review approval is given, merge the PR to kick off the
deployment.

Repeat steps 3 and 4 for each deployment environment target, again following the
merge sequence in the diagram above.

## 5. Tag the release
```bash
git push origin YYYY.0M.R-rcR
```

Once the deploy has completed to `prod`, the version can be tagged and pushed to
GitHub.
This builds a new package and deploys to the Azure test environments. No GitHub release is created for release candidates.

From a local terminal:
## 2. Create a release tag on `main` and push it

```bash
git fetch

git checkout prod

git reset --hard origin/prod

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`-tagged Issue that kicked off the release. Finally, after closing the text editor:
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
```

## 6. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
This builds the package and deploys to the Azure production environments. A GitHub release is created.

## 3. [Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)

Also add a written description, and include screenshots/animations of new/updated pages/workflows.
Edit release notes with additional context, images, animations, etc. as-needed and link to the Release process issue.
28 changes: 28 additions & 0 deletions docs/deployment/rollback.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Making a rollback release

This list outlines the manual steps needed to make a rollback of the
`benefits` 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.

[Start a new Release on Github](https://github.com/cal-itp/benefits/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.
8 changes: 4 additions & 4 deletions docs/deployment/workflows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,21 @@ The GitHub Actions deployment workflow configuration lives at [`.github/workflow

## Deployment steps

The workflow is [triggered][gh-actions-trigger] with a `push` to the corresponding branch. It also responds to the `workflow_dispatch` event to allow manually triggering via the GitHub Actions UI.
The workflow is [triggered][gh-actions-trigger] with a `push` to the `main` branch or when a release candidate or release tag is created on any branch. It also responds to the `workflow_dispatch` event to allow manually triggering via the GitHub Actions UI.

When a deployment workflow runs, the following steps are taken:

### 1. Checkout code

From the tip of the corresponding branch (e.g. `main`)
From the tip of the corresponding branch (e.g. `main`) or the tagged commit

### 2. Authenticate to GHCR

Using the `github.actor` and built-in `GITHUB_TOKEN` secret

### 3. Build and push image to GitHub Container Registry (GHCR)

Build the root [`Dockerfile`][dockerfile], tagging with the SHA from the HEAD commit.
Build the root [`Dockerfile`][dockerfile], tagging with the SHA from the HEAD commit or tagged commit.

Push this image:tag into [GHCR][ghcr].

Expand All @@ -32,6 +32,6 @@ Push this image:tag into [GHCR][ghcr].
Push the new image:tag to the Azure App Service instance.

[deploy]: https://github.com/cal-itp/benefits/blob/main/.github/workflows/deploy.yml
[dockerfile]: https://github.com/cal-itp/benefits/blob/main/Dockerfile
[dockerfile]: https://github.com/cal-itp/benefits/blob/main/appcontainer/Dockerfile
[ghcr]: https://github.com/features/packages
[gh-actions-trigger]: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
9 changes: 7 additions & 2 deletions docs/development/commits-branches-merging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,23 @@ base.

In addition to `main`, the repository has three other long-lived branches:

- `test` and `prod` correspond to the Test and Production [deploy environments](../deployment/README.md), respectively.
- `test` and `prod` are read-only (no longer actively used) and correspond to the Test and Production [deploy environments](../deployment/README.md), respectively. The last release using these branches was [2024.07.1](https://github.com/cal-itp/benefits/releases/tag/2024.07.1).
- `gh-pages` hosts the compiled documentation, and is always forced-pushed by the
[docs build process](../getting-started/documentation.md#deploying).

### Protection rules

[Branch protection rules][gh-branch-protection] are in place on three environment branches (`main`, `test`, `prod`) to:
[Branch protection rules][gh-branch-protection] are in place on `main` to:

- Prevent branch deletion
- Restrict force-pushing, where appropriate
- Require passing status checks before merging into the target branch is allowed

[Branch protection rules][gh-branch-protection] are in place on `test` and `prod` to:

- Prevent branch deletion
- Lock the branch, making it read-only so that users cannot push to the branch since the branch is no longer used

### PR branches

PR branches are typically named with a [conventional type][conventional-commits] prefix, a slash `/`, and then descriptor in `lower-dashed-case`:
Expand Down

0 comments on commit 24b5915

Please sign in to comment.