diff --git a/docs/release_instructions.md b/docs/release_instructions.md new file mode 100644 index 0000000..2199e28 --- /dev/null +++ b/docs/release_instructions.md @@ -0,0 +1,126 @@ +# Release instructions + +## Pre-release checks + +These should run successfully: + +* `make all`; +* `make test`; +* `make lint` (should not change any files); +* `go mod tidy` (should not change any files); + +## Make release commit + +Use `vX.Y.Z` tag for releases and `vX.Y.Z-rc.N` for release candidates +following the [semantic versioning](https://semver.org/) standard. + +Create release branch from the master branch of the origin repository: + +```shell +$ git checkout -b release/ +``` + +### Update versions + +Write new revision number into the root `VERSION` file: + +```shell +$ echo > VERSION +``` + +### Writing changelog + +Use [keepachangelog](https://keepachangelog.com/en/1.1.0/) as a reference. +Add an entry to the `CHANGELOG.md` following the style established there. + +* copy `Unreleased` section (next steps relate to section below `Unreleased`) +* replace `Unreleased` link with the new revision number +* update `Unreleased...new` and `new...old` diff-links at the bottom of the file +* add optional codename and release date in the heading +* make sure all changes have references to issues in `#123` format (if possible) +* check master branch and milestone page for missing changes +* remove all empty subsections such as `Added`, `Removed`, etc. +* clean up `Unreleased` section and leave it empty + +### Make release commit + +Stage changed files for commit using `git add`. Commit the changes: + +```shell +$ git commit -s -m 'Release ' +``` + +### Open pull request + +Push release branch: + +```shell +$ git push release/ +``` + +Open pull request to the master branch of the origin repository so that the +maintainers check the changes. Remove release branch after the merge. + +## Tag the release + +Pull the main branch with release commit created in previous step. + +```shell +$ git checkout master && git pull +$ git tag -a +``` + +Write a short description for the tag, e.g. `Release vX.Y.Z` + +## Push the release tag + +```shell +$ git push +``` + +## Post-release + +### Prepare and push images to a Docker Hub (if not automated) + +Create Docker images for all applications and push them into Docker Hub +(requires [organization](https://hub.docker.com/u/truecloudlab) privileges) + +```shell +$ git checkout +$ make image +$ docker push truecloudlab/frostfs-s3-gw: +``` + +### Make public release page (if not automated) + +Create a new +[release page](https://git.frostfs.info/TrueCloudLab/frostfs-s3-gw/releases/new) +and copy description from `CHANGELOG.md`. Build release binaries and attach them +to the release. Publish the release. + +### Update development environments + +Prepare pull-request in +[frostfs-devenv](https://git.frostfs.info/TrueCloudLab/frostfs-dev-env) +with new versions. + +Prepare pull-request in +[frostfs-aio](https://git.frostfs.info/TrueCloudLab/frostfs-aio) +with new versions. + +### Close milestone + +Look up forgejo +[milestones](https://git.frostfs.info/TrueCloudLab/frostfs-s3-gw/milestones) +and close the release one if exists. + +### Create support branch + +For major or minor release, create support branch in the upstream if it does +not exist yet. + +```shell +$ git checkout +$ git checkout -b support/ +$ git push support/ +``` \ No newline at end of file