From a38ae7c91427537131884620f4cdafb656fe58f5 Mon Sep 17 00:00:00 2001 From: paoloyx Date: Thu, 8 Aug 2024 10:12:39 +0200 Subject: [PATCH] docs: update RELEASE.md document (#162) The document has been rewritten to a better form --- RELEASE.md | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 4a6d9731..6afd561b 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,39 +1,47 @@ # Release Process -This document outlines the steps to release the project. Follow these guidelines to ensure a smooth and consistent release process. +This document outlines the steps required to release the project. Currently, the release process is "semi-automatic," involving the following procedures. + +Adhering to these steps will ensure a smooth and seamless release flow. # Steps to Release ## Create the release PR -We use the [release-please](https://github.com/googleapis/release-please-action) GitHub Action to perform the release. Below you can find the configuration that we use into this repository: +We use the [release-please](https://github.com/googleapis/release-please-action) GitHub Action to perform releases. Configuration details can be found in the following manifests: * [workflow manifest](.github/workflows/release-please.yaml) * [action configuration](.github/release-config.json) -Manually invoke the release-please [workflow](https://github.com/radicalbit/radicalbit-ai-monitoring/actions/workflows/release-please.yaml). The outcome will be the creation of a release PR, that will include the updates to be released, along with the updated [CHANGELOG.md](./CHANGELOG.md) file. +Begin by manually triggering the release-please [workflow](https://github.com/radicalbit/radicalbit-ai-monitoring/actions/workflows/release-please.yaml). This will generate a release PR that includes the updates for release along with the updated [CHANGELOG.md](./CHANGELOG.md) and [version.txt](./version.txt) files. + +**Please ensure that the newly created PR has the `autorelease: pending` label.** ![manually-invoke-release-please](https://github.com/user-attachments/assets/d0245757-c9fc-44b0-bb59-8d91ec23ec1b) -The new release will follow the [semver](https://semver.org) specificationRelease plese will determine the upcoming version bump by parsing the githistoryof the `main` branch, looking for [Conventional Commits](https:/wwwconventionalcommits.org/) messages. +The new release will adhere to the [semver](https://semver.org) specification: release-please will determine the upcoming version bump by parsing the git history of the `main` branch, looking for [Conventional Commits](https:/wwwconventionalcommits.org/) messages. ## (Optional) Update docs version -We use [Docusaurus](https://docusaurus.io) for our documentation. If needed, we must add a new [documentation version](https://docusaurus.io/docs/versioning) created after the same semver tag that will be used for the release. +We use [Docusaurus](https://docusaurus.io) for our documentation. If necessary, add a new [documentation version](https://docusaurus.io/docs/versioning) corresponding to the same semver tag as the upcoming release. -For example, if we were going to release the `v1.2.3` version of the application along updates to its documentation, we would have to release a `v1.2.3` documentation version that will be included into the docs site "version dropdown" +For instance, if releasing version `v1.2.3` of the application that carries updates to its documentation, you should also release a `v1.2.3` documentation version that will be included in the docs site "version dropdown" ![image](https://github.com/user-attachments/assets/e60a4108-8b7d-424a-b11e-a8e44437b258) -To create a new documentation version, please manually invoke the corresponding [workflow](https://github.com/radicalbit/radicalbit-ai-monitoring/actions/workflows/prepare-docs-for-release.yaml) passing two params: +To create a new documentation version, manually invoke the related [workflow](https://github.com/radicalbit/radicalbit-ai-monitoring/actions/workflows/prepare-docs-for-release.yaml) with the following parameters: + +* `version`: the documentation version to be created, matching the application release version (e.g., `v1.2.3`). +* `release-branch`: use `release-please--branches--main` as the branch name. + +Both inputs will be validated, so errors may occur depending on the provided inputs. -* `version`: the documentation version that will be created. Must be the same version of the upcoming application release (`v1.2.3` if we were following the previous example) -* `release-branch`: must be the string `release-please--branches--main` as it's a conventional/default branch name that is used by release-please +## Merge the release PR +Merge the release PR to prepare for the tagged release. **Note that this action does not create a tagged release**; that will occur in the next step. -Please be aware that both inputs will be validated, so you could get errors depending on input passed. ## Perform the release -To perform the release, you must again invoke the release-please [workflow](https://github.com/radicalbit/radicalbit-ai-monitoring/actions/workflows/release-please.yaml). Please carefully check that everything is in order before doing that, as this action will: +To finalize the release, manually trigger the release-please [workflow](https://github.com/radicalbit/radicalbit-ai-monitoring/actions/workflows/release-please.yaml) again. Ensure everything is correct before proceeding, as this step will: -* merge the release PR on `main` branch -* create/push a Git tag that follows the determined semver version i.e. `v1.2.3` -* invoke all github actions that will publish the newly tagged artifacts where necessary i.e. Docker Hub, PyPi, etc. etc. +* create and push a Git tag following the determined semver version (e.g., `v1.2.3`). +* invoke all github actions that will publish the newly tagged artifacts i.e. Docker Hub, PyPi, etc. etc. +* update the release PR label from `autorelease: pending` to `autorelease: tagged`.