Design the semver releases

[afharvey]

Before merging to main I believe we need to add a git tag for semver. Being rust, we need to also change the cargo file (there's a version in there). I believe the git tag and that file should be in sync.

If that's true then we probably want a script and a test which fails if we forget to update them both.

I think default to increasing the patch. I think we just decide what is major and minor otherwise.

• rust, cargo version
• git tag version
• helm chart version

Some projects have separate versions for helm and the code. It's a bit complicated. They even have different kinds of release (under GitHub releases). Maybe we keep it simple and the version is the same everywhere?

Lastly, add a paragraph somewhere so we don't forget. If this can be automated then that'd be super nice.

[jonatanblue]

More than how we sync versioning (I think it will show) between helm and code, just respecting semver is already a win. Too many projects go "1.0.2 has a breaking change from 1.0.1" and think that it's okay.

[jonatanblue]

I'm thinking to add a CI check to make sure version updates are correct and complete, and a release script that updates versions and creates a git tag.

We can merge to main without triggering a new release. Release is a separate PR that requires writing up the changelog and determining which semver section of the version to increment:

• Breaking change -> major
• New functionality, deprecation -> minor
• Bug fix -> patch

Keep Helm and binary versions in sync until we have reason to diverge them.

See what we do repeatedly and automate one thing at a time.

[afharvey]

Kind of related, changelog is a rabbit hole - #28

There's some picky things. For each place we have a version, like the helm chart and docker image, do you have 1.2.3 or v1.2.3. This feels really pedantic but it'd be good to know what normal looks like.

Would be great to know where signing artifacts fits in. Even if we do it later (another rabbit hole). I think we have a secret somewhere, some "well known" path on upgrades.dev, sign the artifact like the image and a tool like "cosign" bundles the signature with the image/files. The consumer can run the same tool, it gets our key from upgrades.dev/some-thing and the hashes are the same. There's an attestation idea as well where you can give confidence the binary was built in a GitHub workflow rather than some hackers laptop.

[jonatanblue]

#28

#69 might perhaps close that issue? I think the key thing is deciding on the changelog format (which is easy: we just use Keep a Changelog), since that could be painful to change later on.

do you have 1.2.3 or v1.2.3

Helm uses versions without the v (https://helm.sh/docs/topics/charts/#charts-and-versioning)
Cargo doesn't allow v at all.
Docker is a mixed bag, I've seen all kinds of version patterns :)
The outlier is github where v1.2.3 is standard

I think v1.2.3 for git and 1.2.3 for the rest.

signing artifacts

I think this is an add-on, as in we are not restricting ourselves in some way that makes this implementation expensive/difficult in future.

[jonatanblue]

Too many projects go "1.0.2 has a breaking change from 1.0.1" and think that it's okay.

This is still a "people problem". I wonder how we can encourage ourselves to be mindful of this.

Added a reminder with semver name: b60e862, so now it says:

Bumping 1.0.0 -> 1.1.0 (minor)