Figure out how to manage versions of packages in the cargo repo

[ehuss]

The cargo repo has several packages which have their own versions independent of the main cargo library. The following are published when cargo-the-library is published every 6 weeks if their version number has changed:

• cargo-util
• cargo-platform
• crates-io

Additionally, there are a few others that are not automatically published, and are only done manually as-needed:

• home
• cargo-credential and the various credential helpers

There have been a few issues where the version numbers haven't been bumped appropriately before the release, causing cargo-the-library to fail, or to be using outdated dependencies.

This issue is to explore different options for how we can better manage the version numbers so that this doesn't happen, and that it takes less manual effort for us to make sure the correct version bumps happen.

Part of the problem is trying to sync with Rust's release cycle. We don't know which changes will ultimately be included in each dependency until the beta branch, which is some arbitrary point over the course of potentially a week. After which, if we need to decide if the collective changes involve a semver-breaking change, we need to push version bumps to both the beta branch and the master branch.

cargo-credential

This is experimental right now. I'm fine with leaving this to be manually managed until it gets to a more serious state where it has the potential to be stabilized.

home

I think we can just manually publish changes whenever new changes come in. I'm not expecting this to change much. I think this is something we could give more attention to if it ends up having more frequent updates.

Dependencies

Option 1: Always semver-breaking bumps

Long ago we used to just always do a semver-breaking version bump for all crates every 6 weeks regardless if they have had any changes. We stopped doing that with the intent that these libraries were intended to be independently usable (particularly cargo-platform). I think it would be good to have these libraries be independently usable without unwanted version bumps.

Option 2: For every PR, check for changes

In CI, we could have a check to see if any changes have been made to a dependency, and check if the dependency's version number has been bumped appropriately.

This runs into some complications with trying to decide if something involves a semver breaking change or not. It would be good to use something like cargo-semver-checks. Unfortunately that depends on an unstable nightly feature, and I'd be reluctant to gate on it in case it stops working. We could perhaps add it in an advisory role, where it could post a comment on the PR if it fails, but not mark the job as failed. If cargo-semver-checks is broken, then we would just need to do manual checks (and we will need to do manual checks regardless since cargo-semver-checks doesn't catch everything).

[epage]

With #12126, what is left for this issue?

[ehuss]

I think we're gone pretty well down option 2's route, but I think there are still some small concerns:

check-version-bump is still a non-required job (I forget why). We're currently in a state where we have to hope that people notice that the job is failing, it isn't actually enforced. This runs the risk, particularly on the beta/stable branch, of not actually knowing that the versions need to be bumped. Also, if we do merge something with a failure, it means the next PR author will get a confusing failure. In practice this isn't so bad, since GitHub sends an email to the author if it fails, but it seems like that could be improved? I'm not exactly sure how, though.

[weihanglo]

check-version-bump is still a non-required job (I forget why).

To me maybe this one tiny reason: cargo-semver-checks is like clippy. It does everything well but may have a few false-positive, or other errors like rustdoc-json version mismatch. We don't want that kind of failures blocking contributions.

That said, we already have random failures from other jobs, and the cargo beta branch-off issue has been resolved via #13827. Maybe we should promote it to a required job and see how stable it is?

BTW I am sure the author of cargo-semver-checks are willing to help if there is really a bug.