cargo: Change prerelease versions to end in ".1-pre" instead of ".0"

[ilyagr]

So, the prerelease version is "0.9.1-pre" instead of "0.9.0".

The main goal is to make it easier to tell from "jj version" output whether it
describes a released version or a prerelease.

According to https://semver.org/#spec-item-9, if taken as a semver, this would
be ordered after "v0.9.0" and before "v0.9.1" (if we need to have a patch
release). If "v0.9.1" was released, we could move on to "v0.9.2-pre".

Cargo docs imply that they follow this spec closely:
https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility

Weirder consequences

"v0.9.1-pre.1" would follow "v0.9.1-pre" if we wanted to publish two
such versions to crate.io for some reason (I don't suggest we do this).

In theory, these are sorted alphabetically, so v0.9.1-beta < v0.9.1-pre < v0.9.1-rc1.
This is confusing, so we should never have .1-alpha or .1-beta
(nor probably .1-rc1) versions. I propose that if we ever have alpha or beta
versions, they should always be .0 versions.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have updated the config schema (cli/src/config-schema.json)
• I have added tests to cover my changes

[ilyagr]

In the end, with #2034, I am thinking of making jj version output for a prerelease to be something like:

jj 0.9.1-pre+20230909-abcdef1234567

The part after + is called "build metadata" in semver spec and is ignored for the purpose of semver ordering. Even though we probably won't ever use that string in a context that strictly requires a semver, we might as well make it so.

One could also argue for jj 0.9.1-pre-20230909+abcdef1234567 or jj 0.9.1-pre.20230909+abcdef1234567, but it's not obvious how those are supposed to compare to the semver jj 0.9.1-pre (actually, according to the spec, the ones with the date would be considered a later version, I think).

[martinvonz]

If we made released versions not include the hash, would that be sufficient?

[ilyagr]

I think having a "-pre" in there makes it clearer that it's a prerelease, regardless of whether there's a commit hash next to it. Less importantly, we'd also then need to have some other way to say "there should be a hash here, but we couldn't figure out what it should be".

I thought this was a cute idea, but I don't think it's terribly important if you don't like it.

[martinvonz]

I think what I don't like about it is that we need to bump the version twice for each release (from 0.x.y-pre to 0.x.y and then to 0.x.(y+1)-pre, IIUC). That sounds like Apache Maven's SNAPSHOT versions, btw (not sure if Maven is still in use). So it's just a little bit of extra work when we cut a release.

I think having a "-pre" in there makes it clearer that it's a prerelease

Yes, and I also think not having "-pre" or a hash makes it clearer that it's a released version. So if you agree, we can start by removing the hash for released versions.

[ilyagr]

So if you agree, we can start by removing the hash for released versions.

I can't think of a good way to do that without also bumping the version twice for each release. If that's too tedious, perhaps both the "-pre" and the hash removal for releases should wait until we have better release automation. I don't think this is at all urgent.

---

The alternative I thought about would be to make something like JJ_RELEASE=1 cargo install or cargo install --feature release to create a binary without a hash in jj version. This would work for official binary releases, but then a user running cargo install jj-cli would get a version with a hash in jj version, which is confusing. Also, all packagers would have to know to add the environment variable (or the hash) to their scripts.

To solve that problem, we'd need to put the information about whether something is a release or a prerelease into the Cargo.toml one way or another (or is there another way for cargo install to behave differently when it's installing from crates.io as opposed to the github repo?). This seems equivalent to two version bumps per release. Then, it'd be easy to only print the hash if the Cargo.toml's version contains -pre.

Finally, we could ignore that problem and have cargo install jj-cli install a binary with a different jj version as compared to the official released binaries. I'm not sure that would be an improvement over the status-quo.

Do you have a better idea? I could look into whether there's a way for cargo install to behave differently when it's installing from crates.io as opposed to the github repo, I suppose.

[martinvonz]

So if you agree, we can start by removing the hash for released versions.

I can't think of a good way to do that without also bumping the version twice for each release.

I was thinking we could make build.rs not add the hash if the tagged version is checked out. We'd have to implement it for both jj and git repos, and maybe also for nix (i don't know what the nix hash there is about).

[ilyagr]

I was thinking we could make build.rs not add the hash if the tagged version is checked out.

It's an interesting idea.

This reminded me to file #2295 that I recently ran into. I'm not sure whether it's critical to fix that before using tags for choosing how to print jj version. I think I thought of using tags at some point, but this experience put me off that idea (though it doesn't have to be fatal to the idea).

I also just realized binaries built with cargo install jj-cli probably already don't include hash in jj version. I'm guessing that command builds jj-cli outside a git repository. I should test it.

We'd have to implement it for both jj and git repos, and maybe also for nix (i don't know what the nix hash there is about).

Yeah, it'd be a bit of a mess I'm afraid.