Skip to content

Commit ad8eb7d

Browse files
rami3lrami3l
committed
docs(dev-guide): update release process with new flow
1 parent 5100b80 commit ad8eb7d

File tree

1 file changed

+120
-49
lines changed

1 file changed

+120
-49
lines changed

‎doc/dev-guide/src/release-process.md‎

Lines changed: 120 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,149 @@
11
# Making a release
22

3+
In rustup, there are two possible release "modes": the beta release and the
4+
official release. The main difference between the two is that they use
5+
different values for the `RUSTUP_UPDATE_ROOT` environment variable:
6+
7+
- A beta release is deployed on `https://dev-static.rust-lang.org/rustup`.
8+
- An official release is deployed on `https://static.rust-lang.org/rustup`.
9+
10+
By switching between those two values, Rustup effectively provides two "self
11+
update channels", making beta testing possible with `rustup self update`.
12+
13+
Currently, rustup does one beta release followed by one official release for
14+
each version number in the increasing order. In other words, we don't release
15+
any `1.28.x` once the `1.29.0` beta release is out, and the latter is followed
16+
by the `1.29.0` stable release, and so on.
17+
18+
## Bumping the version number
19+
20+
The version number is registered in the `Cargo.toml` file of the project.
21+
22+
The general principle for version numbers is that we always increment the
23+
_minor_ number unless:
24+
25+
- A major incompatibility has been introduced in this release:
26+
increment the _major_ number instead.
27+
- This release is a hotfix because the last one had a defect:
28+
increment the _patch_ number instead.
29+
30+
### Minor version bumps
31+
32+
> NOTE: Rustup hasn't been doing major version bumps since a long time ago, but
33+
> if we ever do, the procedure for it should be similar to that of a minor one.
34+
35+
A minor version bump should be performed immediately after the latest `X.Y.0`
36+
(e.g. `1.29.0`) beta release, and to do so, the following steps should be
37+
taken:
38+
39+
- In the `main` branch, note the current minor version number `X.Y` (e.g.
40+
`1.29`) and create a new branch from `main` named `release/X.Y` (e.g.
41+
`release/1.29`). This will be the active backport branch from now on.
42+
- In a separate PR targeting `main`:
43+
- Bump the minor version number in `Cargo.toml` (e.g. to `1.30.0`).
44+
- Run `cargo build` and review `Cargo.lock` changes.
45+
46+
### Patch version bumps
47+
48+
A patch version bump should be performed immediately after any latest release
49+
other than `X.Y.0` betas if the backport branch `release/X.Y` is still
50+
considered active (i.e. it is expected to cut new patch releases from the
51+
branch):
52+
53+
- In a separate PR targeting that backport branch:
54+
- Bump the patch version number in `Cargo.toml` (e.g. to `1.29.1`).
55+
- Run `cargo build` and review `Cargo.lock` changes.
56+
57+
## Maintaining the backport branch
58+
59+
When the backport branch `release/X.Y` is active, you are expected to backport
60+
to it any relevant non-breaking changes one would like to see in new patch
61+
releases. This includes, but is not limited to:
62+
63+
- Bug fixes.
64+
- Patch-compatible documentation improvements.
65+
- Minor features if they are not expected to cause any breakage.
66+
- CI adjustments if relevant to the active backport branch.
67+
68+
The backport PRs should bear the `backport` label and target the active
69+
backport branch in a rebased, commit-preserving manner.
70+
71+
It is OK to backport multiple original PRs at once as long as the conflict
72+
resolution is straightforward (we would expect this to be the case for the most
73+
part otherwise it would be against the point of patch releases in the first
74+
place).
75+
76+
The backport branches already have similar CI setup like that of `main`, but
77+
the full CI must be manually triggered rather than scheduled. To do so, you can
78+
use the [GitHub CLI] under the project directory:
79+
80+
```console
81+
$ gh workflow run ci.yaml --ref release/X.Y
82+
```
83+
84+
## Cutting a new release
85+
386
Before making a release, ensure that `rustup-init.sh` is behaving correctly,
487
and that you're satisfied that nothing in the ecosystem is breaking because
588
of the update. A useful set of things to check includes verifying that
689
real-world toolchains install okay, and that `rust-analyzer` isn't broken by
790
the release. While it's not our responsibility if they depend on non-stable
891
APIs, we should behave well if we can.
992

10-
As a maintainer, you have two options to choose from when cutting a new
11-
release: a beta release or an official release.
12-
The main difference between the two is that they use different values for
13-
the `RUSTUP_UPDATE_ROOT` environment variable:
14-
15-
- A beta release is deployed on `https://dev-static.rust-lang.org/rustup`.
16-
- An official release is deployed on `https://static.rust-lang.org/rustup`.
93+
The next step is to check whether you are cutting a beta or an official release,
94+
and determine which `$BRANCH` you should be working on:
1795

18-
By switching between those two values, Rustup effectively provides two "self
19-
update channels", making beta testing possible with `rustup self update`.
96+
- `main` for `X.Y.0` beta releases.
97+
- `release/X.Y` for any other `X.Y.*` release.
2098

2199
Producing the final release artifacts is a bit involved because of the way
22-
Rustup is distributed.
23-
Below is a list of things to be done in order to cut a new [b]eta release
24-
or an official [r]elease:
25-
26-
1. [b/r] In a separate PR:
27-
1. If the version strings in `Cargo.toml`s haven't been updated:
28-
- Decide what the new version number `$VER_NUM` should be.
29-
> **Note:** We always increment the _minor_ number unless:
30-
>
31-
> - A major incompatibility has been introduced in this release:
32-
> increment the _major_ number instead.
33-
> - This release is a hotfix because the last one had a defect:
34-
> increment the _patch_ number instead.
35-
- Update `Cargo.toml` and `download/Cargo.toml` to have that same new
36-
version number, then run `cargo build` and review `Cargo.lock` changes.
37-
- If all looks well, make a commit.
38-
2. Update `CHANGELOG.md` accordingly if necessary.
39-
2. [b/r] After merging the PR made in step 1, in a separate PR:
40-
1. Update `rustup-init.sh` so that:
100+
Rustup is distributed. Below is a list of things to be done in order to cut a
101+
new [b]eta release or an official [r]elease:
102+
103+
1. [b/r] Make sure that the desired version number for the new release
104+
`$VER_NUM` already exists in `$BRANCH`'s `Cargo.toml` file. Then in a new PR
105+
targeting `$BRANCH`:
106+
1. Update `CHANGELOG.md` accordingly if necessary.
107+
2. Update `rustup-init.sh` so that:
41108
- The version number matches `$VER_NUM`.
42-
- The commit shasum matches the latest commit on `main`.
43-
2. Update the test snapshot of `rustup-init.sh --help`.
109+
- The commit shasum matches the latest commit on `$BRANCH`.
110+
3. Update the test snapshot of `rustup-init.sh --help`.
44111
At the moment of writing, this is done by running:
45112
```console
46113
$ SNAPSHOTS=overwrite cargo test --features=test -- cli_rustup_init_ui
47114
```
48-
3. [b/r] After merging the PR made in step 2, sync `main` to `stable` using
49-
`--ff-only`:
50-
- `git fetch origin main:main`
51-
- `git checkout stable && git merge --ff-only main`
52-
- `git push origin HEAD:stable`
53-
4. [b/r] While you wait for green CI on `stable`, double-check the
115+
2. [b/r] After merging the PR made in step 2:
116+
1. Pull the latest remote `$BRANCH` changes to the local `$BRANCH`.
117+
2. Hard-reset the local `stable` to `$BRANCH`'s tip.
118+
3. Double-check that the current local `stable` is indeed what is expected
119+
for the next release (version number, commit history, etc.)
120+
4. Force-push the local `stable` to the remote `stable`.
121+
3. [b/r] While you wait for green CI on `stable`, double-check the
54122
functionality of `rustup-init.sh` and `rustup-init` just in case.
55-
5. [b/r] Ensure all of CI is green on the `stable` branch.
123+
4. [b/r] Ensure all of CI is green on the `stable` branch.
56124
Once it is, check through a representative proportion of the builds looking
57-
for the reported version statements to ensure that
58-
we definitely built something cleanly which reports as the right version
59-
number when run `--version`.
60-
6. [b] Make a new PR to the [Inside Rust Blog] adding a new "Call for Testing"
125+
for the reported version statements to ensure that we definitely built
126+
something cleanly which reports as the right version number when run
127+
`--version`.
128+
5. [b] Make a new PR to the [Inside Rust Blog] adding a new "Call for Testing"
61129
announcement post.
62-
7. [r] Make a new PR to the [Rust Blog] adding a new release announcement post.
63-
8. [b/r] Ping someone in the release team to perform the actual release.
130+
6. [r] Make a new PR to the [Rust Blog] adding a new release announcement post.
131+
7. [b/r] Ping someone in the release team to perform the actual release.
64132
They can find instructions in `ci/sync-dist.py`.
65133
> **Note:** Some manual testing occurs here, so hopefully they'll catch
66134
> anything egregious in which case abort the change and roll back.
67-
9. [b] Once the beta release has happened, post a new topic named "Seeking beta
135+
8. [b] Once the beta release has happened, post a new topic named "Seeking beta
68136
testers for Rustup $VER_NUM" on the [Internals Forum] to point to the blog
69137
post made previously.
70-
10. [r] Once the official release has happened, prepare and push a tag on the
71-
latest `stable` commit.
72-
- `git tag -as $VER_NUM -m $VER_NUM` (optionally without `-s` if not GPG
73-
signing the tag)
74-
- `git push origin $VER_NUM`
138+
9. [r] Once the official release has happened, prepare and push a tag on the
139+
latest `stable` commit.
140+
- `git tag -as $VER_NUM -m $VER_NUM` (optionally without `-s` if not GPG
141+
signing the tag)
142+
- `git push origin $VER_NUM`
143+
10. [b/r] Immediately perform the corresponding version bump for the next
144+
release as described in the previous sections.
75145

76146
[Rust Blog]: https://github.com/rust-lang/blog.rust-lang.org
77147
[Inside Rust Blog]: https://github.com/rust-lang/blog.rust-lang.org/tree/main/content/inside-rust
78148
[Internals Forum]: https://internals.rust-lang.org
149+
[GitHub CLI]: https://cli.github.com

0 commit comments

Comments
 (0)
⚡