Release 0.15

[wprzytula]

Proposed release notes:

The ScyllaDB team is pleased to announce ScyllaDB Rust Driver 0.15.0,
an asynchronous CQL driver for Rust, optimized for Scylla, but also compatible with Apache Cassandra!

Some interesting statistics:

• over 2.516k downloads on crates!
• over 583 GitHub stars!

Changes

Beginning with this release, instead of putting all API-breaking changes into one group, now they are in the proper categories, but labeled as ⚠️ [API-breaking].

Main changes:

New deserialization API

The main change in this release is the deserialization API refactor. Its primary goal was to reduce overhead caused by all rows being eagerly deserialized to type-erased CqlValue type, only then being converted to end user types.
Old traits and structs (FromCqlVal, FromRow, QueryResult - renamed to LegacyQueryResult, RowIterator - renamed to LegacyRowIterator, TypedRowIterator - renamed to LegacyTypedRowIterator) are replaced by new ones (DeserializeValue, DeserializeRow, new QueryResult, QueryPager, TypedRowStream). There are wrappers and helper implementations provided, designed to aid in gradually migrating to new API - see the migration guide in the book for more information. Old traits and structs will be removed in one of future versions.

New serialization API has a benefit of increased efficiency - now, rows are deserialized straight to the end user type, without any copying and allocations on the way.
Another feature is the ability to deserialize rows to borrowed types (e.g. &str or &[u8]).
And the result metadata is now deserialized in the borrowed form, saving even more allocations.

The refactor included:

• ⚠️ [API-breaking] Parametrized Deserialize{Value,Row} with two lifetimes: 'frame and 'metadata separately (#1101).
• ⚠️ [API-breaking] The deserialization refactor was finished (#1088, #1107, #1109, #1093, #1057, #1120, #1118, #1122, #1121).
• ⚠️ [API-breaking] Unified macro attributes' syntax and semantics between serialization and deserialization derive macros (#1119).

Other changes by category:

New features / enhancements:

• ⚠️ [API-breaking] Made ResultMetadata lifetime-generic, which paved a path to deserializing metadata in a borrowed way as an optimisation to save allocations (#1082).
• Exported serialization migration macros that accidentally hadn't been exported before (#1089).
• Exposed public getters to type-erased errors (#1087).
• Trace message is now issued upon successful keepalive (#1092).
• Added SerializeRow impl for Box<T: SerializeRow> (#1105).
• Exposed public getters for execution profile configuration (#1104).
• Allowed public access to the profile associated with an execution profile handle (#1112).

Bug fixes:

• ⚠️ [API-breaking] Fixed driver's logic that bases on error variants returned from query execution (#1075).
• Fixed possible panic in speculative execution (#1086)
• ⚠️ [API-breaking] Disallowed deserializing Counter type to plain i64 for type safety (#1106).
• Fixed logic about ignoring particular error kinds if speculative execution failed (#1124).

API cleanups / better types:

• ⚠️ [API-breaking] Some of our error types were restructured to be more strongly typed (instead of just containing a string) and better reflect the conditions that they appear in. This work will be continued in 0.16. (#1067, #1074, #1054, #1080, #1080, #1117).
• Removed wildcard re-exports of the serialization framework's entities (#1090).
• ⚠️ [API-breaking] Made RetryPolicy stored behind Arc instead of Box (#1103).

Internal API cleanups/refactors:

• Removed paging state parameter from unpaged raw Connection's API (#1084).
• ⚠️ [API-breaking] Fixed unnameable types in our codebase (by making them exposed, unexposing them or deleting them at all) and enabled the unnameable_types clippy lint to prevent having such situation in the future (#1094).
• Tiny optimizations and code refactors (#1108).

Documentation:

• Updated docs theme (#1081, #1110).

CI / developer tool improvements:

• clippy was appeased again (#1072, #1077, #1095).
• Pinned Rust version in book.yml CI workflow (#1096).

Others:

• Rewritten RELEASE.md, so that it now contains up-to-date guide about maintaining and releasing the driver (#1076).
• Bumped MSRV to 1.70 (#1098).
• Added an example showing Counter UPDATE (#1100).

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
  Contributions are most welcome!

The official crates.io registry entry is here:

• 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
154	Mikołaj Uzarski
89	Wojciech Przytuła
45	Karol Baryła
26	Piotr Dulikowski
3	David Garcia
1	Daniel Boll
1	Alex Pozhylenkov

[wprzytula]

Version bump commits etc. are still to be done; I opened this so that the release notes can already be reviewed.

[wprzytula]

Aha, removing the only commit by a force push auto-closes the PR. Good to know, GitHub.

[github-actions]

cargo semver-checks found no API-breaking changes in this PR! 🎉🥳
Checked commit: f59908c

[Lorak-mmk]

Proposed release notes:

The ScyllaDB team is pleased to announce ScyllaDB Rust Driver 0.15.0, an asynchronous CQL driver for Rust, optimized for Scylla, but also compatible with Apache Cassandra!

Some interesting statistics:

* over 2.516k downloads on crates!

* over 583 GitHub stars!

Changes

New deserialization API

The main change in this release is the deserialization API refactor. Its primary goal was to reduce overhead caused by all rows being eagerly deserialized to type-erased CqlValue type, only then being converted to end user types. Old traits and structs (FromCqlVal, FromRow, QueryResult - renamed to LegacyQueryResult, RowIterator - renamed to LegacyRowIterator, TypedRowIterator - renamed to LegacyTypedRowIterator) are replaced by new ones (DeserializeValue, DeserializeRow, new QueryResult, QueryPager, TypedRowStream). There are wrappers and helper implementations provided, designed to aid in gradually migrating to new API - see the migration guide in the book for more information. Old traits and structs will be removed in one of future versions.

New serialization API has a benefit of increased efficiency - now, rows are deserialized straight to the end user type, without any copying and allocations on the way. Another feature is the ability to deserialize rows to borrowed types (e.g. &str or &[u8]). And the result metadata is now deserialized in the borrowed form, saving even more allocations.

Changes by category:

Bug fixes:

Could you move this section below API breaking changes and new features?

* Fixed driver's logic that bases on error variants returned from query execution ([#1075](https://github.com/scylladb/scylla-rust-driver/pull/1075)).

* Fixed possible panic in speculative execution ([#1086](https://github.com/scylladb/scylla-rust-driver/pull/1086))

* Disallowed deserializing Counter type to plain `i64` for type safety ([#1106](https://github.com/scylladb/scylla-rust-driver/pull/1106)).

* Fixed logic about ignoring particular error kinds if speculative execution failed ([#1124](https://github.com/scylladb/scylla-rust-driver/pull/1124)).

API cleanups / breaking changes:

* Parametrized `Deserialize{Value,Row}` with two lifetimes: `'frame` and `'metadata` separately ([#1101](https://github.com/scylladb/scylla-rust-driver/pull/1101)).

* The deserialization refactor was finished ([#1088](https://github.com/scylladb/scylla-rust-driver/pull/1088), [#1107](https://github.com/scylladb/scylla-rust-driver/pull/1107), [#1109](https://github.com/scylladb/scylla-rust-driver/pull/1109), [#1093](https://github.com/scylladb/scylla-rust-driver/pull/1093), [#1057](https://github.com/scylladb/scylla-rust-driver/pull/1057), [#1120](https://github.com/scylladb/scylla-rust-driver/pull/1120), [#1118](https://github.com/scylladb/scylla-rust-driver/pull/1118), [#1122](https://github.com/scylladb/scylla-rust-driver/pull/1122), [#1121](https://github.com/scylladb/scylla-rust-driver/pull/1121)).

* Unified macro attributes' syntax and semantics between serialization and deserialization derive macros ([#1119](https://github.com/scylladb/scylla-rust-driver/pull/1119)).

* Some of our error types were restructured to be more strongly typed (instead of just containing a string) and better reflect the conditions that they appear in. This work will be continued in 0.16. ([#1067](https://github.com/scylladb/scylla-rust-driver/pull/1067), [#1074](https://github.com/scylladb/scylla-rust-driver/pull/1074), [#1054](https://github.com/scylladb/scylla-rust-driver/pull/1054), [#1080](https://github.com/scylladb/scylla-rust-driver/pull/1074), [#1080](https://github.com/scylladb/scylla-rust-driver/pull/1080), [#1117](https://github.com/scylladb/scylla-rust-driver/pull/1117)).

* Removed wildcard re-exports of the serialization framework's entities ([#1090](https://github.com/scylladb/scylla-rust-driver/pull/1090)).

* Made `RetryPolicy` stored behind `Arc` instead of `Box` ([#1103](https://github.com/scylladb/scylla-rust-driver/pull/1103)).

New features / enhancements:

* Made `ResultMetadata` lifetime-generic, which paved a path to deserializing metadata in a borrowed way as an optimisation to save allocations ([#1082](https://github.com/scylladb/scylla-rust-driver/pull/1082)).

This is a breaking change, no? Shouldn't it be in the section about breaking changes?
Actually now that I think of it, several items here and in the "bug fixes" and "interal API cleanups" are breaking and are not in the API breaking section. Moving them to the API breaking section loses a bit of information - because there we don't differentiate between fixes, enhancements etc. Maybe a better idea would be to have a "Main changes" section for things like deserialization refactor that are a highlight of a release, and put other breaking changes in other sections (bugfixes / enhacements etc) and mark them somehow, so that the API-breaking items are visible on the list?

I have two idea on how to mark such items.
First:

• ⚠️ [API Breaking] Made ResultMetadata lifetime-generic, which paved a path to deserializing metadata in a borrowed way as an optimisation to save allocations (#1082).

Second:

Warning

[API Breaking] Made ResultMetadata lifetime-generic, which paved a path to deserializing metadata in a borrowed way as an optimisation to save allocations (#1082).

I think I like the first one more. It would also be good to include a node about this notation as it would be different than in previous releases.

* Exported serialization migration macros that accidentally hadn't been exported before ([#1089](https://github.com/scylladb/scylla-rust-driver/pull/1089)).

* Exposed public getters to type-erased errors ([#1087](https://github.com/scylladb/scylla-rust-driver/pull/1087)).

* Trace message is now issued upon successful keepalive ([#1092](https://github.com/scylladb/scylla-rust-driver/pull/1092)).

* Added `SerializeRow` impl for `Box<T: SerializeRow>` ([#1105](https://github.com/scylladb/scylla-rust-driver/pull/1105)).

* Exposed public getters for execution profile configuration ([#1104](https://github.com/scylladb/scylla-rust-driver/pull/1104)).

* Allowed public access to the profile associated with an execution profile handle ([#1112](https://github.com/scylladb/scylla-rust-driver/pull/1112)).

Internal API cleanups/refactors:

* Removed paging state parameter from unpaged raw `Connection`'s API ([#1084](https://github.com/scylladb/scylla-rust-driver/pull/1084)).

* Fixed unnameable types in our codebase (by making them exposed, unexposing them or deleting them at all) and enabled the `unnameable_types` clippy lint to prevent having such situation in the future ([#1094](https://github.com/scylladb/scylla-rust-driver/pull/1094)).

* Tiny optimizations and code refactors ([#1108](https://github.com/scylladb/scylla-rust-driver/pull/1108)).

Documentation:

* Updated docs theme ([#1081](https://github.com/scylladb/scylla-rust-driver/pull/1081), [#1110](https://github.com/scylladb/scylla-rust-driver/pull/1110)).

CI / developer tool improvements:

* clippy was appeased again ([#1072](https://github.com/scylladb/scylla-rust-driver/pull/1072), [#1077](https://github.com/scylladb/scylla-rust-driver/pull/1077), [#1095](https://github.com/scylladb/scylla-rust-driver/pull/1095)).

* Pinned Rust version in `book.yml` CI workflow ([#1096](https://github.com/scylladb/scylla-rust-driver/pull/1096)).

Others:

* Rewritten RELEASE.md, so that it now contains up-to-date guide about maintaining and releasing the driver ([#1076](https://github.com/scylladb/scylla-rust-driver/pull/1076)).

* Bumped MSRV to 1.70 ([#1098](https://github.com/scylladb/scylla-rust-driver/pull/1098)).

* Added an example showing Counter UPDATE ([#1100](https://github.com/scylladb/scylla-rust-driver/pull/1100)).

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
  Contributions are most welcome!

The official crates.io registry entry is here:

* 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
154 Mikołaj Uzarski
89 Wojciech Przytuła
45 Karol Baryła
26 Piotr Dulikowski
3 David Garcia
1 Daniel Boll
1 Alex Pozhylenkov

[wprzytula]

Could you move this section below API breaking changes and new features?

I could, but why? Aren't bug fixes more important than new features?

[Lorak-mmk]

Could you move this section below API breaking changes and new features?

I could, but why? Aren't bug fixes more important than new features?

Define important.
If we talk about priorities of development then I don't think there is a clear winner.
If you talk about what is marketable / interesting to users, then I think features are much more important. Release notes are a form of promotion.