Usage with cocogitto / conventional commits

[oknozor]

Hello, I am the author of cocogitto, a conventional commits-based release manager.
I came across cargo-semver-check at FOSDEM 2024, and it made me wonder how I could use it along with cocogitto.

Cocogitto calculates the next version number based on the repository's conventional commit history and performs a set of user-defined commands to create a release with the expected tag. It's great for automating the whole release process, but ultimately, we trust user commits to calculate the next version number.

Unfortunately, I cannot integrate cargo-semver-check the same way release-plz does. Cocogitto does not use PRs to release, and it supports any language, so I cannot use cargo-semver-check by default.

My idea is to integrate cargo-semver-check both into the release process and as a commit hook. But I think that would require a subcommand that outputs the suggested version bump or accepts a target SemVer tag.

Release management example: For instance, I trigger a version bump with cocogitto from version 1.0.0; it calculates a minor bump. Before writing the new tag, I want to ensure the tag calculated by cocogitto matches cargo-semver-check's output.

Conventional commits example: I am done working on this new feature in my project and create a new feature commit, following the conventional commit specification. cargo-semver-check runs as a post-commit hook along with cocogitto; they both output a next version number. If those numbers do not match, I probably need to rewrite my commit message so it has the correct conventional commit type.

I am not sure if this is currently possible with cargo semver checks.
If not, I would like to contribute to make that possible. What would be the best approach for this?

[obi1kenobi]

Release management example: For instance, I trigger a version bump with cocogitto from version 1.0.0; it calculates a minor bump. Before writing the new tag, I want to ensure the tag calculated by cocogitto matches cargo-semver-check's output.

This should just be a cargo semver-checks invocation by itself, possibly with --release-type=major if cocogitto thinks the bump should be major. (Right now that will be a no-op, but it won't be a no-op forever — in the future we'll have lints that are still run on major releases and act as warnings, not errors.)

By default cargo semver-checks will use the largest already-released version number that is <= the current version in Cargo.toml. This seems to match what this case needs.

If the package in question is not on crates.io then you could specify the baseline as a git tag or another way. The FAQ and --help list a few different options.

Conventional commits example: I am done working on this new feature in my project and create a new feature commit, following the conventional commit specification. cargo-semver-checks runs as a post-commit hook along with cocogitto; they both output a next version number. If those numbers do not match, I probably need to rewrite my commit message so it has the correct conventional commit type.

For some complex reasons, it's better to use a slightly tweaked approach where no version numbers are computed.

The conventional commit makes a claim on whether there are any breaking changes or not.

cargo-semver-checks also checks for breaking changes. If it finds nothing but the commit says it's breaking, that's fine. But if the commit says it isn't breaking and cargo-semver-checks finds breakage, that should be brought to the user's attention.

In this case, you'll want to use a git baseline with the commit hash of the previous commit (not the one in the process of being created). This should again work fairly seamlessly.

The one caveat is that currently baseline rustdoc JSON files that aren't generated from a crates.io version are not cached. This is a tradeoff: the JSON files can often be very large, and unlike cocogitto, cargo-semver-checks isn't tied into the overall workflow so it doesn't know what kind of cache eviction policy is safe to apply.

Depending on the project size you're working with, it may at some point be a good idea to start thinking about managing a rustdoc JSON cache to speed up the pre-commit hook. Or, perhaps it might be better to run it as a post-commit check in some fashion, so that the user isn't kept waiting. As maintainer of cocogitto, I leave those UX questions to you — I just wanted to flag a potential future concern early :)