diff --git a/docs/releases.md b/docs/releases.md index ef17b24a..884d0d42 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -21,3 +21,53 @@ All versions of the package may be viewed on the [package all versions page](htt 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 `2024.01.1` release would be `2024.01.1-rc1`. + +## Making a release + +This list outlines the manual steps needed to make a new release of `eligibility-server`. + +A release is made by pushing an annotated tag. The name of the tag must use the version number format mentioned above. 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 about the deployment steps and release creation can be found in the [`docker-publish`](https://github.com/cal-itp/eligibility-server/tree/main/.github/workflows/docker-publish.yml) workflow. [`release`](https://github.com/cal-itp/eligibility-server/tree/main/.github/workflows/release.yml) workflow. + +The list of releases can be found on the [repository Releases page](https://github.com/cal-itp/eligibility-server/tags) on GitHub. + +[Start a new Release on Github](https://github.com/cal-itp/eligibility-server/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 the release candidate version. Finally, after closing the text editor: + +```bash +git push origin YYYY.0M.R-rcR +``` + +This builds a new package and deploys to the Azure test environments. 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-tagged Issue that kicked off the release. Finally, after closing the text editor: + +```bash +git push origin YYYY.0M.R +``` + +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) + +Edit release notes with additional context, images, animations, etc. as-needed and link to the release issue. diff --git a/mkdocs.yml b/mkdocs.yml index f241edfe..c824b502 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,7 @@ extra_css: markdown_extensions: - admonition + - attr_list - codehilite: linenums: true - pymdownx.inlinehilite