diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml index 37aabf9014..52cc36140c 100644 --- a/.github/workflows/docs-pages.yaml +++ b/.github/workflows/docs-pages.yaml @@ -6,7 +6,8 @@ on: push: branches: - main - - 'branch-**' + tags: + - 'v0.*' paths: - "docs/**" workflow_dispatch: diff --git a/MAINTENANCE.md b/MAINTENANCE.md new file mode 100644 index 0000000000..7c56c2fa4b --- /dev/null +++ b/MAINTENANCE.md @@ -0,0 +1,287 @@ +# Maintenance + +The following document includes information how to release scylla-rust-driver and +other information / procedures useful for maintainers. + +## Crates and versions + +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 on `scylla-cql` and `scylla-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 on `scylla-macros`. +- `scylla-proxy`: mostly internal crate that aids testing. Depends on `scylla-cql`. + +We publish all 4 crates on [crates.io](https://crates.io/crates/scylla). + +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. + + +## Documentation + +There are 2 places where documentation is published: +- [docs.rs](https://docs.rs/scylla/latest/scylla/): API docs, generated automatically when publishing a crate to [crates.io](https://crates.io/crates/scylla). +- [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. + +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](https://rust-driver.docs.scylladb.com/stable/). + +`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: + +![The warning about unstable version](assets/unstable.png) + +`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: + +![The warning about deprecated version](assets/deprecated.png) + +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. + +## Branches and tags + +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](https://mermaid.js.org/). If you view this file on GitHub it should be rendered correctly. +You can also view it using [mermaid.live](https://mermaid.live) + +```mermaid +--- +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" +``` + +## Version bump commits + +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 relevant `Cargo.toml` +- Version number in crates that depend on given crate (so a commit bumping `scylla-macros` will also change version of +`scylla-macros` in `scylla` and `scylla-cql` crates). +- Version number of the crate in `Cargo.lock.msrv` + +Additionally the last commit (which bumps `scylla` crate version) changes: +- `docs/pyproject.toml` and `docs/source/conf.py`, as described in "Documentation" section. +- Version number in `docs/source/quickstart/create-project.md`. + +## Backporting + +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`. + +## Releasing + +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](https://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. + +### Releasing a major version + +1. Check out current `main`, e.g. `git fetch; git checkout origin/main`. +2. Create a new version branch, e.g. `git checkout -b "branch-0.14.x"`. +3. Create commits that bump version numbers of the crates (see `Version bump commits` section in this document). +4. Push the new branch to our repo (e.g. `git push origin branch-0.14.x`). +5. Prepare release notes (see the template at the bottom of this document). +6. (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 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. +7. Checkout `main` and fast-forward merge the new branch (e.g. `git checkout main; git merge --ff-only branch-0.14.x`). +6. Create a new tag (e.g. `git tag -a v0.14.0 -m "Release 0.14.0"`). +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/). +10. Go to the "Common steps" section below. + +### Releasing a minor version + +1. Checkout the correct version branch (e.g. `git checkout "branch-0.14.x"`). +2. Create some new branch (which you'll later push to your fork). +3. Perform any backports that are missing from the release. +3. Create commits that bump version numbers of the crates (see `Version bump commits` section in this document). +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. +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. +5. Checkout version branch (e.g. `git checkout "branch-0.14.x"`) and fast-forward merge your changes (`git merge --ff-only your_branch`). +6. Create a new tag (e.g. `git tag -a v0.14.1 -m "Release 0.14.1"`). +7. Push version branch and new tag, preferably using atomic push (e.g. `git push --atomic origin branch-0.14.x v0.14.1`). +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/). +9. Go to the "Common steps" section below. + +### Common steps + +1. Verify that documentation book was published at [Documentation book](https://rust-driver.docs.scylladb.com/stable/). +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 ` for each crate that is being updated, in correct order (`scylla-macros`, `scylla-cql`, `scylla-proxy`, `scylla`). +3. Verify that new versions are visible on crates.io and their docs on docs.rs. +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. +5. (Mandatory for major release, optional for minor release) Publish a post on the forum: + - Go to [Release notes](https://forum.scylladb.com/c/scylladb-release-notes/18) section. + - Click "New Topic". + - Title should be `[RELEASE] ScyllaDB Rust Driver `, 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! + + +## Writing release notes + +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` + (or `git shortlog previous_major_version_tag..HEAD -s -n`, assuming that a major + version tag is on a commit present in `main` 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! + + +## Release notes template + +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 | + +``` + diff --git a/RELEASE.md b/RELEASE.md deleted file mode 100644 index a9a573373f..0000000000 --- a/RELEASE.md +++ /dev/null @@ -1,23 +0,0 @@ -# Release procedure - -The following list includes information how to release version vX.Y.Z of scylla-rust-driver - -0. Be a maintainer of this project with write rights to this repository and crates.io/crates/scylla -1. Check out current `main`, e.g. `git fetch; git checkout origin/main` -2. Run `./scripts/prepare-release.sh X.Y.Z` - this script will prepare a release commit with the version bumped in appropriate places and also create a local vX.Y.Z git tag; - feel free to verify the commit with `git log -p -1` after the script was executed successfully -3. Push the commit to scylladb/scylla-rust-driver `main` branch, e.g. `git push origin HEAD:refs/heads/main` -4. Push the newly created tag to scylladb/scylla-rust-driver, e.g. `git push origin vX.Y.Z` -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 -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. -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. -8. Send the release notes to scylladb-users (https://groups.google.com/g/scylladb-users) as well as Cassandra users (https://lists.apache.org/list.html?user@cassandra.apache.org) mailing lists. -9. Publish the documentation for the new version. In `docs/source/conf.py`, -update the following: -- `TAGS = [' ']` - add the new release tag to the list -- `LATEST_VERSION = ' '` - replace the previous tag with the new release tag - -You're done! - - diff --git a/assets/deprecated.png b/assets/deprecated.png new file mode 100644 index 0000000000..8d3f072fd9 Binary files /dev/null and b/assets/deprecated.png differ diff --git a/assets/unstable.png b/assets/unstable.png new file mode 100644 index 0000000000..04df013928 Binary files /dev/null and b/assets/unstable.png differ diff --git a/scripts/prepare-release.sh b/scripts/prepare-release.sh deleted file mode 100755 index b1ef1e2a88..0000000000 --- a/scripts/prepare-release.sh +++ /dev/null @@ -1,20 +0,0 @@ -#!/bin/sh - -if [ "$#" -ne 1 ]; then - echo "Usage: $0 " - exit 1 -fi - -new_release=$1 -root_dir=$(git rev-parse --show-toplevel) - -echo "Preparing release ${new_release}" -echo "Root repo directory: ${root_dir}" - -sed -i "s/^version =.*/version = \"${new_release}\"/g" ${root_dir}/docs/pyproject.toml -sed -i "s/^version =.*/version = \"${new_release}\"/g" ${root_dir}/scylla/Cargo.toml - -git add ${root_dir}/docs/pyproject.toml ${root_dir}/scylla/Cargo.toml -git commit -m "scylla: bump version to ${new_release}" -git tag v${new_release} -