We need a more rigorous versioning and release process

[trishankatdatadog]

As @arbll has observed, go-tuf is going through a lot of breaking changes quite regularly now. This is good as in the project is seeing a lot of healthy development to meet the community's needs. However, it is also bad in that if we don't inform our consumers about breaking changes, they are unable to decide how much work they to do in order to consume a new release.

Therefore, I highly recommend that we define and agree on a versioning and release process. It does not have to be SemVer (partly because the MAJOR version will regularly get bumped now, which makes no sense either), but we do need to come up with a process, preferably as automated as possible.

@joshuagl, any thoughts, as you have a lot of experience in this area?

[shibumi]

There are no go-tuf releases yet. I would still argue for semver. Instead of bumping the MAJOR version all the time you can bump the MINOR version. Go-Tuf is still heavily in development, I think every party would be ok with having a few 0.X.Y releases before go-tuf gets a stable release with v1.0.0.

If you want to be very explicit abou this you can add a suffix to the version like: v0.1.0-alpha.1.

In my opinion, the most important part is providing a good changelog. It might make sense to switch to conventional commits: https://www.conventionalcommits.org/en/v1.0.0/

With conventional commits it's very convenient to read the changelog and identify breaking changes, feature additions, bug fixes etc. But this means that every developer has to add a prefix to the commit messages.

That's just my small experience as package maintainer at a Linux distribution :) There might be better ideas.

[asraa]

Going to add this to contributing doc!
I think it would be very, very useful to keep a changelog.

[joshuagl]

Great discussion topic. Completely agree that we should be making releases of go-tuf and trying to pay more attention to our API stability such that changes are intentional and communicated.

SemVer feels like a sane approach, we aren't making an API stability promise until we make a release with a major version greater than 0 – from item 4 of the SemVer spec:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

With explicit releases, users can pin to a release and choose when to update. Changelogs help them understand what they are getting in that release and conventional commits are a great way to help collect the information.

Once we have caught up with the spec, defined any refactoring we might want to do, and intentionally groomed the API we want to support we can start communicating intent to make a 1.0 release.

[joshuagl]

Just added "The Principles of Versioning in Go" by Russ Cox to my reading list, as it feels like it could be relevant to this discussion

[trishankatdatadog]

SemVer feels like a sane approach, we aren't making an API stability promise until we make a release with a major version greater than 0 – from item 4 of the SemVer spec:

💯

SemVer has its drawbacks, but we could do worse.

Are there automated release processes we can steal/copy from python-tuf, Joshua?

[ethan-lowman-dd]

We discussed using https://goreleaser.com/ for automation

[shibumi]

There is a PR for goreleaser support + keyless signatures via cosign: #157
goreleaser can also produce changelogs and in combination with conventional commits we can separate them into Features/Bugfixes/etc.
I think this is really helpful and could increase the developer experience a lot.

[trishankatdatadog]

See #200 for a community resolution.

[trishankatdatadog]

Should we close this discussion now that we have an issue open for it? Otherwise, easy to have orphaned discussions. I think a pathway should be discussion -> issue -> PR.

[shibumi]

Let's move the discussion around this into: #200 + my Goreleaser PR. I think my PR is related to the issue.

[trishankatdatadog]

I have no strong feelings, but yes, let's try to resolve your issue in #200 also

[trishankatdatadog]

Oh, ideally, we should have created an issue from this discussion. We will try to remember doing that going forward. Also, doesn't look like you can close discussions, so we'll just leave it as it is for now.