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/<vX.Y.Z>
+```
+
+### Update versions
+
+Write new revision number into the root `VERSION` file:
+
+```shell
+$ echo <vX.Y.Z> > 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 <vX.Y.Z>'
+```
+
+### Open pull request
+
+Push release branch:
+
+```shell
+$ git push <origin> release/<vX.Y.Z>
+```
+
+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 <vX.Y.Z>
+```
+
+Write a short description for the tag, e.g. `Release vX.Y.Z`
+
+## Push the release tag
+
+```shell
+$ git push <upstream> <vX.Y.Z>
+```
+
+## 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 <vX.Y.Z>
+$ make image
+$ docker push truecloudlab/frostfs-s3-gw:<X.Y.Z>
+```
+
+### 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 <vX.Y.0>
+$ git checkout -b support/<vX.Y>
+$ git push <upstream> support/<vX.Y>
+```