From ea0147af19942e7c3e3e322b34a3dd3a6b1f8461 Mon Sep 17 00:00:00 2001 From: Marcel Moura Date: Fri, 12 Apr 2024 11:05:51 -0300 Subject: [PATCH] docs: describe release process --- CHANGELOG.md | 2 +- README.md | 4 +++ docs/release.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/release.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 186241768..9c619d8ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [unreleased] +## [Unreleased] ### Added diff --git a/README.md b/README.md index cd1ff4865..70a58d4de 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,10 @@ Check the [development](docs/development.md) page for more information about dev This document covered the features of the Node and its external APIs in a high-level manner. Check the [architecture](docs/architecture.md) page for more details about the Node internal components. +## Releasing + +Check the [release](docs/release.md) page for more information about the steps to release a version of the Rollups Node. + ## Contributing Thank you for your interest in Cartesi! diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 000000000..5f3381f27 --- /dev/null +++ b/docs/release.md @@ -0,0 +1,92 @@ +# Release process + +This page explains how to create a release of the Rollups Node by showing each step that should be performed, from updating the change log and testing the changes to announcing a release. + +## Pre-release procedure + +Before starting the release process, we must confirm all project dependencies have been updated for the new release. + +All related tasks are described in the [update-dependencies issue template](https://github.com/cartesi/rollups-node/blob/main/.github/ISSUE_TEMPLATE/update-dependencies.md). + +## Pull latest changes + +On your local machine, make sure to pull the latest changes made to the `main` branch. + +## Perform tests + +Execute all end-to-end tests and whatever specific tests concerning the changes made at the release (let's use `X.Y.Z` as the release version number). + +If necessary, fix any issues with the team by following the normal development workflow. + +Once all tests pass and the `main` branch is up-to-date, proceed to the next step. + +## Update the [`CHANGELOG`](../CHANGELOG.md) + +Confirm the code changes listed under `Unreleased` are accurate, and then: + +- in the beginning of the file, replace the heading `Unreleased` with the version number of the new release, followed by the current date (`YYYY-MM-DD`); +- at the end of the file, create a link to the differences from the new release to the previous one; +- update the link to the differences related to the `Unreleased` changes. + +Commit the changes, push them to the repository and create a corresponding pull request. + +> [A sample commit](https://github.com/cartesi/rollups-node/commit/16ba20137a1575b98d069500168261cccb2e0eb2) may be found in the repository. + +## Create the release tag + +Once the pull request is approved, merge it and update your local copy of the `main` branch. + +Then, create a new tag for the release based on the `main` branch as follows: + +```shell +git tag -a vX.Y.Z +``` + +Make sure to add a message to the tag commit as follows: + +```txt +Release X.Y.Z +``` + +Then, push the tag to th repository: + +```sh +git push origin vX.Y.Z +``` + +## Check CI results + +Check if the CI actions associated with the release pass. + +After that, pull the docker image generated by the CI to make sure it's been pushed to Docker hub as follows: + +```shell +docker pull cartesi/rollups-node:X.Y.Z +``` + +## Update release information + +Go to the [Releases page](https://github.com/cartesi/rollups-node/releases) and edit the current release by: + +- unchecking the `Set as a pre-release`; +- checking the `Set as the latest release`. + +Remember to save the changes after that. + +## Announce the release + +Once the release information is updated, announce it on the appropriate communication channels. +The announcement should contain: + +- the release number; +- a link to the tag/release; +- instructions on how to pull the corresponding docker image from Docker hub. + +## Update/create a maintenance branch + +Either create a maintenance branch for any major or minor release and name it as `release/X.Y.x` or update an existing maintenance branch if the release is a patch release. + +## Prepare for the next release + +Last but not least, prepare the [`CHANGELOG`](../CHANGELOG.md) for the next release by creating a new heading (`## [Unreleased]`) in the beginning of the document. +Create a pull request based on the `main` branch and merge it once it's approved.