Increment version numbers for next release and update guidance (#1229)

Set up new guidance for incrementing version numbers and implement it
for Mountpoint and the client crates.

Under the new guidance, the patch version will be incremented
immediately after releasing Mountpoint or publishing the crates, so that
development on `main` continues under a new provisional version.
When new features / breaking changes are introduced, the version number
will be contextually incremented as the changes are documented in the
changelog.

### Does this change impact existing behavior?

No

### Does this change need a changelog entry?

No

---

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license and I agree to the terms of
the [Developer Certificate of Origin
(DCO)](https://developercertificate.org/).

---------

Signed-off-by: Alessandro Passaro <alexpax@amazon.co.uk>

.github/pull_request_template.md

@@ -6,9 +6,9 @@
 
 **TODO: Please confirm there's no breaking change, or call out any that are made.**
 
-### Does this change need a changelog entry?
+### Does this change need a changelog entry? Does it require a version change?
 
-**TODO: Confirm with justification if not added.**
+**TODO: Confirm with justification if not required.**
 
 ---
 

doc/CONTRIBUTING.md

@@ -64,6 +64,22 @@ Here is the full list of changelog files we maintain for reference.
 - https://github.com/awslabs/mountpoint-s3/blob/main/mountpoint-s3-crt/CHANGELOG.md
 - https://github.com/awslabs/mountpoint-s3/blob/main/mountpoint-s3-crt-sys/CHANGELOG.md
 
+### Version numbers
+
+Mountpoint and the other `mountpoint-s3-*` crates in this repository follow [semantic versioning](https://semver.org/) rules. After we release Mountpoint or [publish the
+other crates](https://github.com/awslabs/mountpoint-s3/blob/main/mountpoint-s3-client/PUBLISHING_CRATES.md), we provisionally increase the patch version number
+of the corresponding crate.
+
+When a pull request is submitted, we consider whether the changes it contains should trigger a version number increment by comparing the latest released
+version with the one on `main`. If a pull request introduces a new Mountpoint feature, we make sure that the minor version of the `mountpoint-s3`
+crate is incremented compared to the latest release, if it was not already. The crate's `CHANGELOG.md` will show the latest released version and all the more
+recent changes under the `Unreleased` section. Example:
+
+* A pull request introduces a new feature and adds an entry to the changelog,
+* The latest release, as reported on the changelog, is `1.13.0`,
+* The version on `main` is `1.13.1`,
+* The minor version number must be incremented, so the new version should be `1.14.0`.
+
 ## Finding contributions to work on
 
 Looking at the existing issues is a great way to find something to contribute on. We use issue labels to identify [good first issues](https://github.com/awslabs/mountpoint-s3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) as a great place to start.

mountpoint-s3-client/Cargo.toml

@@ -1,15 +1,15 @@
 [package]
 name = "mountpoint-s3-client"
 # See `/mountpoint-s3-client/PUBLISHING_CRATES.md` to read how to publish new versions.
-version = "0.11.0"
+version = "0.12.0"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/awslabs/mountpoint-s3"
 description = "High-performance Amazon S3 client for Mountpoint for Amazon S3."
 
 [dependencies]
-mountpoint-s3-crt = { path = "../mountpoint-s3-crt", version = "0.10.0" }
-mountpoint-s3-crt-sys = { path = "../mountpoint-s3-crt-sys", version = "0.10.0" }
+mountpoint-s3-crt = { path = "../mountpoint-s3-crt", version = "0.11.0" }
+mountpoint-s3-crt-sys = { path = "../mountpoint-s3-crt-sys", version = "0.11.0" }
 
 async-trait = "0.1.83"
 auto_impl = "1.2.0"

mountpoint-s3-client/PUBLISHING_CRATES.md

@@ -4,14 +4,17 @@ This document guides maintainers in releasing new versions of [`mountpoint-s3-cl
 
 ## Preparing the release
 
-First, a commit should be prepared and merged which updates the versions of each of the crates that are changing
-as well as a change log for each detailing what has been updated.
-You can refer to the following pull request as an example of this commit: https://github.com/awslabs/mountpoint-s3/pull/657.
+First, confirm that for each crate:
 
-The change log should have been updated when the changes were made, but please verify this.
+* `CHANGELOG.md` lists the relevant changes since the latest released version,
+* `Cargo.toml` sets the version that you intend to publish.
 
-The `Cargo.toml` manifest for each crate that will have a new version should be updated with the new version number.
-Additionally, crates which depend on the updated crates should have their dependencies updated.
+Second, prepare a new commit to update each `CHANGELOG.md` file by adding a header for the new release with
+the current date under the `## Unreleased` header. E.g.:
+
+```
+## v0.10.0 (October 17, 2024)
+```
 
 Once ready, check everything still compiles and publish a pull request.
 After that is merged, the next step is to publish the new crates.
@@ -54,3 +57,14 @@ For each crate replacing the crate and version number where applicable:
    ```
 
 Once these steps have been completed for all crates that need to be updated, you're done.
+
+## Update to next versions
+
+After all the crates have been published, a commit should be prepared which increments the patch version number of each crate,
+in its `Cargo.toml`, as well as in the crates depending on it.
+
+E.g. if `mountpoint-s3-crt-sys-0.99.0` was just published, `mountpoint-s3-crt-sys/Cargo.toml` should be updated to `version = "0.99.1"`
+and the corresponding entry in `mountpoint-s3-crt/Cargo.toml` should be updated to
+`mountpoint-s3-crt-sys = { path = "../mountpoint-s3-crt-sys", version = "0.99.1" }`.
+
+Once ready, check everything still compiles and publish a pull request.

mountpoint-s3-crt-sys/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "mountpoint-s3-crt-sys"
 # See `/mountpoint-s3-client/PUBLISHING_CRATES.md` to read how to publish new versions.
-version = "0.10.0"
+version = "0.11.0"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/awslabs/mountpoint-s3"

mountpoint-s3-crt/Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "mountpoint-s3-crt"
 # See `/mountpoint-s3-client/PUBLISHING_CRATES.md` to read how to publish new versions.
-version = "0.10.0"
+version = "0.11.0"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/awslabs/mountpoint-s3"
 description = "Rust interface to the AWS Common Runtime for Mountpoint for Amazon S3."
 
 [dependencies]
-mountpoint-s3-crt-sys = { path = "../mountpoint-s3-crt-sys", version = "0.10.0" }
+mountpoint-s3-crt-sys = { path = "../mountpoint-s3-crt-sys", version = "0.11.0" }
 
 futures = "0.3.31"
 libc = "0.2.168"

mountpoint-s3/Cargo.toml

@@ -1,15 +1,15 @@
 [package]
 name = "mountpoint-s3"
-version = "1.14.0"
+version = "1.14.1"
 edition = "2021"
 license = "Apache-2.0"
 publish = false
 default-run = "mount-s3"
 
 [dependencies]
 fuser = { path = "../vendor/fuser", version = "0.15.0", features = ["abi-7-28"] }
-mountpoint-s3-client = { path = "../mountpoint-s3-client", version = "0.11.0" }
-mountpoint-s3-crt = { path = "../mountpoint-s3-crt", version = "0.10.0" }
+mountpoint-s3-client = { path = "../mountpoint-s3-client", version = "0.12.0" }
+mountpoint-s3-crt = { path = "../mountpoint-s3-crt", version = "0.11.0" }
 
 anyhow = { version = "1.0.94", features = ["backtrace"] }
 async-channel = "2.3.1"