The following document includes information how to release scylla-rust-driver and other information / procedures useful for maintainers.
This workspace consists of 4 crates:
scylla
: main driver crate to be used by users; the only one expected to be added as a dependency and have items imported from (i.e. the only "public" crate). Depends onscylla-cql
andscylla-macros
.scylla-macros
: provides derive macros for users to be able to use their structs as UDTs / query parameters.scylla-cql
: low-level implementation of CQL binary protocol. Depends onscylla-macros
.scylla-proxy
: mostly internal crate that aids testing. Depends onscylla-cql
.
We publish all 4 crates on crates.io.
Versions of the crates are decided with strict accordance to semver. For sources on semver and semver in rust see:
- https://doc.rust-lang.org/cargo/reference/resolver.html
- https://doc.rust-lang.org/cargo/reference/semver.html
- https://semver.org/
- 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).
What needs to be considered for releasing:
- You mustn't change major version of scylla-cql / scylla-macros dependency in a minor update of scylla crate. 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.
- 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 arguments for that, but I can't remember them.
There are 2 places where documentation is published:
- docs.rs: API docs, generated automatically when publishing a crate to crates.io.
- Documentation book: generated and published by our CI (see docs-pages.yaml) when there is a push to either
main
or to somev0.*
tag.
Parameters relevant to releasing documentation book are configured in docs/source/conf.py
and docs/pyproject.toml
files.
In pyproject.toml
there is the version
field - we do update it but I don't think it affects anything.
In docs/conf.py
there are TAGS
, BRANCHES
, LATEST_VERSION
, UNSTABLE_VERSIONS
and DEPRECATED_VERSIONS
fields.
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.
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.
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:
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:
IMPORTANT: docs/source/conf.py
for rendering documentation is always taken from the main
branch - even if a push to branch-*
triggered the job.
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.
It however means that any release requires updating conf.py
on main
branch to have the new version rendered on documentation book.
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).
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
.
All new development lands on main
branch, and may be backported by maintainers to version branches.
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
.
Each such tag has a message of the form Release 0.X.Y
(e.g. Release 0.14.0
).
Below is a simplified view of how this looks. Diagrams created using mermaid.js. If you view this file on GitHub it should be rendered correctly. You can also view it using mermaid.live
---
title: Rust Driver git branches
---
gitGraph
commit id: "Feature A"
commit id: "Release 0.13" tag: "v0.13.0"
branch branch-0.13.x
checkout branch-0.13.x
commit id: "Backport fix C"
commit id: "Release 0.13.1" tag: "v0.13.1"
commit id: "Backport fix D"
commit id: "Release 0.13.2" tag: "v0.13.2"
checkout main
commit id: "Feature B"
commit id: "Fix C"
commit id: "Release 0.14" tag: "v0.14.0"
branch branch-0.14.x
checkout branch-0.14.x
commit id: "Backport fix D " %% Space at the end because mermaid doesn't
%% allow duplicate labels and totally breaks the graph without this space
commit id: "Release 0.14.1" tag: "v0.14.1"
checkout main
commit id: "Fix D"
For simplicity the graph in previous section suggested that version bumps happen in one commit. In reality we bump each crate version in a separate commit.
For an example, see four last commits of this PR: https://github.com/scylladb/scylla-rust-driver/pull/1040/commits
Commits that update scylla-proxy
/ scylla-macros
/ scylla-cql
change:
version
field in relevantCargo.toml
- Version number in crates that depend on given crate (so a commit bumping
scylla-macros
will also change version ofscylla-macros
inscylla
andscylla-cql
crates). - Version number of the crate in
Cargo.lock.msrv
Additionally the last commit (which bumps scylla
crate version) changes:
docs/pyproject.toml
anddocs/source/conf.py
, as described in "Documentation" section.- Version number in
docs/source/quickstart/create-project.md
.
We perform backports using cherry-picks.
Please always use -x
flag for cherry-pick to record information about original commit.
It will add to the bottom of the commit message a line like (cherry picked from commit 5752af488655287fc332ec3dd68645ef522e0d7c)
If you want to backport a whole PR, you should cherry-pick the merge commit.
You will need -m
flag for that - it selects which is the "main" parent.
Typically you will use "-m 1", because first parent is the main one (think main
branch),
and second one is PR branch.
That means the typical command to backport whole PR is git cherry-pick -x -m 1 commit-sha
.
You can also backport a single commit - which can be part of a PR branch or not, doesn't matter.
In this case you don't need -m
flag, you can just do git cherry-pick -x commit-sha
.
IMPORTANT: Read this whole document before attempting to do a release.
Prerequisites:
- Have write access to GitHub repo (so that you are able to push to main and create a new branch).
- Have access to our crates on crates.io.
- 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.
- Check out current
main
, e.g.git fetch; git checkout origin/main
. - Create a new version branch, e.g.
git checkout -b "branch-0.14.x"
. - Create commits that bump version numbers of the crates (see
Version bump commits
section in this document). - Push the new branch to our repo (e.g.
git push origin branch-0.14.x
). - Prepare release notes (see the template at the bottom of this document).
- (Optional, but recommended) Create a PR from the new branch to
main
so that another maintainer can review your work. 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 wantmain
andbranch-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. - Checkout
main
and fast-forward merge the new branch (e.g.git checkout main; git merge --ff-only branch-0.14.x
). - Create a new tag (e.g.
git tag -a v0.14.0 -m "Release 0.14.0"
). - 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. - Go to the "Common steps" section below.
- Checkout the correct version branch (e.g.
git checkout "branch-0.14.x"
). - Create some new branch (which you'll later push to your fork).
- Perform any backports that are missing from the release.
- Create commits that bump version numbers of the crates (see
Version bump commits
section in this document). - (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. 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.
- Checkout version branch (e.g.
git checkout "branch-0.14.x"
) and fast-forward merge your changes (git merge --ff-only your_branch
). - Create a new tag (e.g.
git tag -a v0.14.1 -m "Release 0.14.1"
). - Push version branch and new tag, preferably using atomic push (e.g.
git push --atomic origin branch-0.14.x v0.14.1
). - 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. - Go to the "Common steps" section below.
- Verify that documentation book was published at Documentation book.
- 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
). - Verify that new versions are visible on crates.io and their docs on docs.rs.
- 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. - (Mandatory for major release, optional for minor release) Publish a post on the forum:
- Go to Release notes section.
- Click "New Topic".
- Title should be
[RELEASE] ScyllaDB Rust Driver <version>
, e.g.[RELEASE] ScyllaDB Rust Driver 0.14.0
- Tags:
release
,drivers
,rust-driver
,rust
. - Content of the post should just be release notes.
- Click "Create Topic"
- Posts in "Release notes" section need additional confirmation. You can write to current forum admin to expedite this.
You're done!
PR titles are written for maintainers, but release notes entries are written for users. It means that they should not be the same - and if they are then they are probably not good as either PR titles or release notes entries.
For that reason we hand-write our release notes, and link to relevant PRs in the entries.
Some old release notes that you can take inspiration from when writing new ones:
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.10.0
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.14.0
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.11.0
- https://github.com/scylladb/scylla-rust-driver/releases/tag/v0.13.0
The template for release notes can be found in the section below.
Guidelines on how to write release notes:
-
Go over all the PRs / commits since previous release. Usually:
git log --first-parent
to see merge commits and commits that are directly on a branch. You can also try filtering merged PRs on Github by merge date, but it's cumbersome. -
Items in release notes will usually correspond 1:1 to PRs / comits - but not always. It is possible that some functionality that should be a single item on the list is split over multiple PRs. It is also possible that single PR will be mentioned in two items.
-
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.
-
Release notes for major version should contain a table with number of commits per contributor. You can generate this data with a command
git shortlog $(git merge-base main previous_version_tag)..HEAD -s -n
(orgit shortlog previous_major_version_tag..HEAD -s -n
, assuming that a major version tag is on a commit present inmain
branch, as it should be). This table should not count version bump commits - subtract them from your row if you already created them. -
Release notes for minor version should NOT contain the aforementioned list.
-
Remember to update the amount of crate downloads and Gtihub stars!
PR numbers in the list are random, they are just here to emphasize that entries should contain links to relevant PR / PRs.
The ScyllaDB team is pleased to announce ScyllaDB Rust Driver 0.X.0,
an asynchronous CQL driver for Rust, optimized for Scylla, but also compatible with Apache Cassandra!
Some interesting statistics:
- over 2.103k downloads on crates!
- over 556 GitHub stars!
## Changes
**API cleanups / breaking changes:**
- Some breaking change 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
- Some breaking change 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
**New features / enhancements:**
- Some new feature 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
- Some new feature 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
**Documentation:**
- Doc update 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
- Doc update 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
**CI / developer tool improvements:**
- Update 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
- Update 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
**Others:**
- Update 1 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
- Update 2 ([123](https://github.com/scylladb/scylla-rust-driver/pull/123))
Congrats to all contributors and thanks everyone for using our driver!
----------
The source code of the driver can be found here:
- [https://github.com/scylladb/scylla-rust-driver](https://github.com/scylladb/scylla-rust-driver)
Contributions are most welcome!
The official crates.io registry entry is here:
- [https://crates.io/crates/scylla](https://crates.io/crates/scylla)
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!
Contributors since the last release:
| commits | author |
|---------|-------------------|
| 45 | Lucille Perkins |
| 34 | Rachel Burton |
| 17 | Mercedes Marks |