Skip to content

Commit 011dd42

Browse files
Lorak-mmkLorak-mmk
committed
RELEASE.md: Rewrite release procedure documentation
This document was really outdated and did not reflect current structure of the project and our current release procedures. This commit basically rewrites it from scratch, adding a lot of useful details and information, which will be beneficial for current and future maintainers.
1 parent 1a92c3c commit 011dd42

File tree

3 files changed

+283
-19
lines changed

3 files changed

+283
-19
lines changed

‎RELEASE.md

+283-19
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,287 @@
1-
# Release procedure
2-
3-
The following list includes information how to release version vX.Y.Z of scylla-rust-driver
4-
5-
0. Be a maintainer of this project with write rights to this repository and crates.io/crates/scylla
6-
1. Check out current `main`, e.g. `git fetch; git checkout origin/main`
7-
2. Run `./scripts/prepare-release.sh X.Y.Z`
8-
this script will prepare a release commit with the version bumped in appropriate places and also create a local vX.Y.Z git tag;
9-
feel free to verify the commit with `git log -p -1` after the script was executed successfully
10-
3. Push the commit to scylladb/scylla-rust-driver `main` branch, e.g. `git push origin HEAD:refs/heads/main`
11-
4. Push the newly created tag to scylladb/scylla-rust-driver, e.g. `git push origin vX.Y.Z`
12-
5. Write release notes. You can find an example here: https://groups.google.com/g/scylladb-users/c/uOfmdTeq6qM or here: https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.5.0
13-
6. Go to https://github.com/scylladb/scylla-rust-driver/releases , click the `Draft new release` button and follow the procedure to create a new release on GitHub. Use the release notes as its description.
14-
7. Publish the crate(s) on crates.io. For `scylla` crate, go directly to the crate directory, i.e. `/your/repo/path/scylla-rust-driver/scylla`, and run `cargo publish`. It will ask you for an access token, follow the instructions if you haven't set one up.
15-
8. Send the release notes to scylladb-users (https://groups.google.com/g/scylladb-users) as well as Cassandra users (https://lists.apache.org/[email protected]) mailing lists.
16-
9. Publish the documentation for the new version. In `docs/source/conf.py`,
17-
update the following:
18-
- `TAGS = [' ']` - add the new release tag to the list
19-
- `LATEST_VERSION = ' '` - replace the previous tag with the new release tag
1+
# Maintenance
2+
3+
The following document includes information how to release scylla-rust-driver and
4+
other information / procedures useful for maintainers.
5+
6+
## Crates and versions
7+
8+
This workspace consists of 4 crates:
9+
- `scylla`: main driver crate to be used by users;
10+
the only one expected to be added as a dependency and have items imported from (i.e. the only "public" crate).
11+
Depends on `scylla-cql` and `scylla-macros`.
12+
- `scylla-macros`: provides derive macros for users to be able to use their structs as UDTs / query parameters.
13+
- `scylla-cql`: low-level implementation of CQL binary protocol. Depends on `scylla-macros`.
14+
- `scylla-proxy`: mostly internal crate that aids testing. Depends on `scylla-cql`.
15+
16+
We publish all 4 crates on [crates.io](https://crates.io/crates/scylla).
17+
18+
Versions of the crates are decided with strict accordance to semver.
19+
For sources on semver and semver in rust see:
20+
- https://doc.rust-lang.org/cargo/reference/resolver.html
21+
- https://doc.rust-lang.org/cargo/reference/semver.html
22+
- https://semver.org/
23+
- https://rust-lang.github.io/api-guidelines/necessities.html#public-dependencies-of-a-stable-crate-are-stable-c-stable (and some other parts of this book).
24+
25+
What needs to be considered for releasing:
26+
- You mustn't change major version of scylla-cql / scylla-macros dependency in a minor update of scylla crate.
27+
For example, if scylla 0.13.0 depends on scylla-cql 0.4, then scylla 0.13.1 mustn't depend on scylla-cql 0.5.
28+
- We typically bump major versions of all 3 main crates (`scylla`, `scylla-cql`, `scylla-macros`) together. I'm not sure if it's necessary - I remember there were
29+
arguments for that, but I can't remember them.
30+
31+
32+
## Documentation
33+
34+
There are 2 places where documentation is published:
35+
- [docs.rs](https://docs.rs/scylla/latest/scylla/): API docs, generated automatically when publishing a crate to [crates.io](https://crates.io/crates/scylla).
36+
- [Documentation book](https://rust-driver.docs.scylladb.com/stable/): generated and published by our CI (see [docs-pages.yaml](https://github.com/scylladb/scylla-rust-driver/blob/main/.github/workflows/docs-pages.yaml)) when there is a push to either `main` or to some `v0.*` tag.
37+
38+
Parameters relevant to releasing documentation book are configured in `docs/source/conf.py` and `docs/pyproject.toml` files.
39+
In `pyproject.toml` there is the `version` field - we do update it but I don't think it affects anything.
40+
In `docs/conf.py` there are `TAGS`, `BRANCHES`, `LATEST_VERSION`, `UNSTABLE_VERSIONS` and `DEPRECATED_VERSIONS` fields.
41+
42+
`TAGS` and `BRANCHES` are lists of tags and branches for which documentation book will be built - those 2 lists add up to a list of versions you see when you click "expand" a version list in the left upper corner of [documentation book](https://rust-driver.docs.scylladb.com/stable/).
43+
44+
`LATEST_VERSION` selects the element from the above list that will be the default ("stable") version shown when visiting https://rust-driver.docs.scylladb.com/stable/index.html.
45+
46+
`UNSTABLE_VERSIONS` is a subset of `TAGS + BRANCHES`. If a version is on this list it will have a note in rendered documentation informing about instability:
47+
48+
![The warning about unstable version](assets/unstable.png)
49+
50+
`DEPRECATED_VERSIONS` is a subset of `TAGS + BRANCHES`. If a version is on that list then it will have a similar note informing about deprecation:
51+
52+
![The warning about deprecated version](assets/deprecated.png)
53+
54+
IMPORTANT: `docs/source/conf.py` for rendering documentation is always taken from the `main` branch - even if a push to `branch-*` triggered the job.
55+
If that was not the case we would have to always synchronize `conf.py` on all supported branches - right now we only need to have it correct on `main` branch.
56+
57+
It however means that **any release requires updating `conf.py` on `main` branch** to have the new version rendered on documentation book.
58+
59+
## Branches and tags
60+
61+
We maintain a branch per major release (after releasing 1.0 we may change to a branch per minor release - this is yet to be decided). This is done so that we are able to release an update for older major release (e.g. release 0.13.3 after 0.14.0 is released).
62+
Major version branches are named `branch-0.A.x`, where `A` is a number of the version. Example: branch for `0.14` will be `branch-0.14.x`.
63+
64+
All new development lands on `main` branch, and may be backported by maintainers to version branches.
65+
66+
Each release of `scylla` crate has a corresponding git tag. Tags are named `vA.B.C`, so release `0.14.1` will have tag `v0.14.1`.
67+
Each such tag has a message of the form `Release 0.X.Y` (e.g. `Release 0.14.0`).
68+
69+
Below is a simplified view of how this looks.
70+
Diagrams created using [mermaid.js](https://mermaid.js.org/). If you view this file on GitHub it should be rendered correctly.
71+
You can also view it using [mermaid.live](https://mermaid.live)
72+
73+
```mermaid
74+
---
75+
title: Rust Driver git branches
76+
---
77+
gitGraph
78+
commit id: "Feature A"
79+
commit id: "Release 0.13" tag: "v0.13.0"
80+
branch branch-0.13.x
81+
checkout branch-0.13.x
82+
commit id: "Backport fix C"
83+
commit id: "Release 0.13.1" tag: "v0.13.1"
84+
commit id: "Backport fix D"
85+
commit id: "Release 0.13.2" tag: "v0.13.2"
86+
checkout main
87+
commit id: "Feature B"
88+
commit id: "Fix C"
89+
commit id: "Release 0.14" tag: "v0.14.0"
90+
branch branch-0.14.x
91+
checkout branch-0.14.x
92+
commit id: "Backport fix D " %% Space at the end because mermaid doesn't
93+
%% allow duplicate labels and totally breaks the graph without this space
94+
commit id: "Release 0.14.1" tag: "v0.14.1"
95+
checkout main
96+
commit id: "Fix D"
97+
```
98+
99+
## Version bump commits
100+
101+
For simplicity the graph in previous section suggested that version bumps happen in one commit.
102+
In reality we bump each crate version in a separate commit.
103+
104+
For an example, see four last commits of this PR: https://github.com/scylladb/scylla-rust-driver/pull/1040/commits
105+
106+
Commits that update `scylla-proxy` / `scylla-macros` / `scylla-cql` change:
107+
- `version` field in relevant `Cargo.toml`
108+
- Version number in crates that depend on given crate (so a commit bumping `scylla-macros` will also change version of
109+
`scylla-macros` in `scylla` and `scylla-cql` crates).
110+
- Version number of the crate in `Cargo.lock.msrv`
111+
112+
Additionally the last commit (which bumps `scylla` crate version) changes:
113+
- `docs/pyproject.toml` and `docs/source/conf.py`, as described in "Documentation" section.
114+
- Version number in `docs/source/quickstart/create-project.md`.
115+
116+
## Backporting
117+
118+
We perform backports using cherry-picks.
119+
120+
Please always use `-x` flag for cherry-pick to record information about original commit.
121+
It will add to the bottom of the commit message a line like `(cherry picked from commit 5752af488655287fc332ec3dd68645ef522e0d7c)`
122+
123+
If you want to backport a whole PR, you should cherry-pick the merge commit.
124+
You will need `-m` flag for that - it selects which is the "main" parent.
125+
Typically you will use "-m 1", because first parent is the main one (think `main` branch),
126+
and second one is PR branch.
127+
128+
That means the typical command to backport whole PR is `git cherry-pick -x -m 1 commit-sha`.
129+
130+
You can also backport a single commit - which can be part of a PR branch or not, doesn't matter.
131+
In this case you don't need `-m` flag, you can just do `git cherry-pick -x commit-sha`.
132+
133+
## Releasing
134+
135+
IMPORTANT: Read this whole document before attempting to do a release.
136+
137+
Prerequisites:
138+
- Have write access to GitHub repo (so that you are able to push to main and create a new branch).
139+
- Have access to our crates on [crates.io](https://crates.io).
140+
- For each of our 3 crates in this workspace (`scylla-macros`, `scylla-cql`, `scylla`) decide if it needs a new version, and if so, what is the correct version number. See "Crates and versions" section.
141+
142+
### Releasing a major version
143+
144+
1. Check out current `main`, e.g. `git fetch; git checkout origin/main`.
145+
2. Create a new version branch, e.g. `git checkout -b "branch-0.14.x"`.
146+
3. Create commits that bump version numbers of the crates (see `Version bump commits` section in this document).
147+
4. Push the new branch to our repo (e.g. `git push origin branch-0.14.x`).
148+
5. Prepare release notes (see the template at the bottom of this document).
149+
6. (Optional, but recommended) Create a PR from the new branch to `main` so that another maintainer can review your work.
150+
Description of this PR should consist of just release notes. **NOTE: Don't merge this PR using GitHub interface - just wait for approval.** The reason is that we want `main` and `branch-XX` to point to the same commit after merge, but Github doesn't have fast-forward merges in GUI - it will however detect such merge done in Git CLI and mark the PR as merged.
151+
7. Checkout `main` and fast-forward merge the new branch (e.g. `git checkout main; git merge --ff-only branch-0.14.x`).
152+
6. Create a new tag (e.g. `git tag -a v0.14.0 -m "Release 0.14.0"`).
153+
9. Push `main` and new tag, preferably using atomic push (e.g. `git push --atomic origin main v0.14.0`). This should build book documentation and publish it on [Documentation book](https://rust-driver.docs.scylladb.com/stable/).
154+
10. Go to the "Common steps" section below.
155+
156+
### Releasing a minor version
157+
158+
1. Checkout the correct version branch (e.g. `git checkout "branch-0.14.x"`).
159+
2. Create some new branch (which you'll later push to your fork).
160+
3. Perform any backports that are missing from the release.
161+
3. Create commits that bump version numbers of the crates (see `Version bump commits` section in this document).
162+
4. (Optional, but recommended) Push the branch to your fork and create the PR to the version branch so that another maintainer can review your work.
163+
Description of this PR should consist of just release notes. **NOTE: Preferably merge this PR with CLI as described in next step. If you really want to use GitHub UI only use REBASE merge.** This is to make all commits appear on the version branch, without any merge commits / squash commits.
164+
5. Checkout version branch (e.g. `git checkout "branch-0.14.x"`) and fast-forward merge your changes (`git merge --ff-only your_branch`).
165+
6. Create a new tag (e.g. `git tag -a v0.14.1 -m "Release 0.14.1"`).
166+
7. Push version branch and new tag, preferably using atomic push (e.g. `git push --atomic origin branch-0.14.x v0.14.1`).
167+
8. Create a new commit on `main` that updates documentation version - see "Documentation" section in this document. This should build book documentation and publish it on [Documentation book](https://rust-driver.docs.scylladb.com/stable/).
168+
9. Go to the "Common steps" section below.
169+
170+
### Common steps
171+
172+
1. Verify that documentation book was published at [Documentation book](https://rust-driver.docs.scylladb.com/stable/).
173+
2. Publish all updated crates to crates.io. Make sure you are using newest stable version of Rust. In the main folder of the repository run `cargo publish -p <crate>` for each crate that is being updated, in correct order (`scylla-macros`, `scylla-cql`, `scylla-proxy`, `scylla`).
174+
3. Verify that new versions are visible on crates.io and their docs on docs.rs.
175+
4. Go to https://github.com/scylladb/scylla-rust-driver/releases , click the `Draft new release` button and follow the procedure to create a new release on GitHub. Use the release notes as its description.
176+
5. (Mandatory for major release, optional for minor release) Publish a post on the forum:
177+
- Go to [Release notes](https://forum.scylladb.com/c/scylladb-release-notes/18) section.
178+
- Click "New Topic".
179+
- Title should be `[RELEASE] ScyllaDB Rust Driver <version>`, e.g. `[RELEASE] ScyllaDB Rust Driver 0.14.0`
180+
- Tags: `release`, `drivers`, `rust-driver`, `rust`.
181+
- Content of the post should just be release notes.
182+
- Click "Create Topic"
183+
- Posts in "Release notes" section need additional confirmation. You can write to current forum admin to expedite this.
20184

21185
You're done!
22186

23187

188+
## Writing release notes
189+
190+
PR titles are written for maintainers, but release notes entries are written for users.
191+
It means that they should not be the same - and if they are then they are probably
192+
not good as either PR titles or release notes entries.
193+
194+
For that reason we hand-write our release notes, and link to relevant PRs in the entries.
195+
196+
Some old release notes that you can take inspiration from when writing new ones:
197+
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.10.0
198+
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.14.0
199+
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.11.0
200+
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.13.0
201+
202+
The template for release notes can be found in the section below.
203+
204+
Guidelines on how to write release notes:
205+
206+
- Go over all the PRs / commits since previous release. Usually: `git log --first-parent` to see
207+
merge commits and commits that are directly on a branch. You can also try filtering
208+
merged PRs on Github by merge date, but it's cumbersome.
209+
210+
- Items in release notes will usually correspond 1:1 to PRs / comits - but not always. It is possible that
211+
some functionality that should be a single item on the list is split over multiple PRs.
212+
It is also possible that single PR will be mentioned in two items.
213+
214+
- Release notes for a a major version should contain all changes since the previous major version. Release notes for a minor version should contain all changes since previous version.
215+
216+
- Release notes for **major** version should contain a table with number of commits per contributor.
217+
You can generate this data with a command
218+
`git shortlog $(git merge-base main previous_version_tag)..HEAD -s -n`
219+
(or `git shortlog previous_major_version_tag..HEAD -s -n`, assuming that a major
220+
version tag is on a commit present in `main` branch, as it should be).
221+
This table should not count version bump commits - subtract them from your
222+
row if you already created them.
223+
224+
- Release notes for **minor** version should NOT contain the aforementioned list.
225+
226+
- Remember to update the amount of crate downloads and Gtihub stars!
227+
228+
229+
## Release notes template
230+
231+
PR numbers in the list are random, they are just here to emphasize that entries
232+
should contain links to relevant PR / PRs.
233+
234+
```
235+
The ScyllaDB team is pleased to announce ScyllaDB Rust Driver 0.X.0,
236+
an asynchronous CQL driver for Rust, optimized for Scylla, but also compatible with Apache Cassandra!
237+
238+
Some interesting statistics:
239+
240+
- over 2.103k downloads on crates!
241+
- over 556 GitHub stars!
242+
243+
## Changes
244+
245+
**API cleanups / breaking changes:**
246+
- Some breaking change 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
247+
- Some breaking change 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
248+
249+
**New features / enhancements:**
250+
- Some new feature 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
251+
- Some new feature 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
252+
253+
**Documentation:**
254+
- Doc update 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
255+
- Doc update 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
256+
257+
**CI / developer tool improvements:**
258+
- Update 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
259+
- Update 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
260+
261+
**Others:**
262+
- Update 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
263+
- Update 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
264+
265+
Congrats to all contributors and thanks everyone for using our driver!
266+
267+
----------
268+
269+
The source code of the driver can be found here:
270+
- [https://github.com/scylladb/scylla-rust-driver](https://github.com/scylladb/scylla-rust-driver)
271+
Contributions are most welcome!
272+
273+
The official crates.io registry entry is here:
274+
- [https://crates.io/crates/scylla](https://crates.io/crates/scylla)
275+
276+
Thank you for your attention, please do not hesitate to contact us if you have any questions, issues, feature requests, or are simply interested in our driver!
277+
278+
Contributors since the last release:
279+
280+
| commits | author |
281+
|---------|-------------------|
282+
| 45 | Lucille Perkins |
283+
| 34 | Rachel Burton |
284+
| 17 | Mercedes Marks |
285+
286+
```
287+

‎assets/deprecated.png

75.4 KB
Loading

‎assets/unstable.png

70.4 KB
Loading

0 commit comments

Comments
 (0)