1# How to release a new version
2
3## When to release a new version
4
5New version should be released when we are ready to make changes generally available.
6
7New version should not be released if we want to test our latest changes or to make them available to a limited number of users. This can be achieved without releasing a new version. Go modules allow to point to latest main or specific Git commit. However, commits from main are not suitable for use in production unless they are a release tag. Do not use non-release commits in downstream projects in production.
8
9Consider releasing a new Release Candidate version to make changes available to a larger group of users, if we are not ready to make them available to everyone yet.
10
11Under no circumstances may releases be done during the weekend or the wee hours of the night.
12
13## Version numbers
14
15We follow the rules for semantic versioning, but prefixed with the letter `v`.
16
17Examples of official releases:
18- `v1.0.0`
19- `v1.0.3`
20- `v1.2.3`
21- `v2.1.7`
22
23Examples of Release Candidates:
24- `v1.0.0-rc.4`
25- `v2.1.0-rc.1`
26
27## Step-by-step release process
28
291. Clone or fetch latest main of these Git repositories:
30  - https://github.com/storj/storj
31  - https://github.com/storj/gateway-st
32  - https://github.com/storj/gateway-mt
33  - https://github.com/storj/uplink-c
342. For each of them update, `go.mod` and `testsuite/go.mod` to latest main (or the specific Git commit that will be tagged as a new version) of `storj.io/uplink`. Makefile target `bump-dependencies` (available in all listed repositories) can bo used to do this automatically.
353. Use `go mod tidy` to update the respective `go.sum` files.
364. Push a change to Gerrit with the updated `go.mod` and `go.sum` files for each of the Git repositories.
375. Wait for the build to finish. If the build fails for any of the Git repositories, abort the release process. Investigate the issue, fix it, and start over the release process.
386. If all builds are successful, do not merge the changes yet.
397. If you haven't done this yet, announce your intention to make a new release to the #libuplink Slack channel.
408. Wait for a confirmation by at least one maintainer of this project (storj/uplink) before proceeding with the next step.
419. Create a new release from the Github web interface:
42  - Go to https://github.com/storj/uplink/releases.
43  - Click the `Draft a new release` button.
44  - Enter `Tag version` following the rules for the version number, e.g. `v1.2.3`.
45  - Enter the same value as `Release title`, e.g. `v1.2.3`.
46  - If there are new commits in main since you executed step 1, do not include them in the release. Change the `Target` from `main` to the specific Git commit used in step 1.
47  - Describe the changes since the previous release in a human-readable way. Only those changes that affect users. No need to describe refactorings, etc.
48  - If you are releasing a new Release Candidate, select the `This is a pre-release` checkbox.
49  - Save a draft and paste release link into the #libuplink Slack channel for review and wait for approval.
50  - Click the `Publish release` button.
5110. Update the Gerrit changes from step 1 with the new official version number.
5211. Wait for the build to finish again and merge them.
53