Semantic versioning & changelogs

[Maelstromeous]

Project really needs Conventional commit changelogs and releases, also displayed on the website.

Commit messages need to be in this format:

feat(web): Done a thing
fix(parser): Fixed a bug with game data

Currently playing with commit-and-tag-version, however having issues with it detecting feat currently as a 0.x.x version bump instead of a 0.0.x. https://github.com/absolute-version/commit-and-tag-version/issues/205

[Maelstromeous]

For now, main deployments are going to be tracked by vercel, and I'll just have to manually trigger version bumps. Without it working correctly locally, I don't want GitHub Actions to take control of the versioning just yet. Really puzzled as to why the package is not detecting feat as a 0.X.0 bump, proper strange.

[samsmithnz]

Have you looked at GitVersion before? I've found it very reliable for GitHub Actions versioning. Most of my websites use it, for example: https://github.com/samsmithnz/SatisfactoryTree/releases.

Automatic Commit logs/Releases is a tricky problem. At this scale it's probably easier to just manually update the webpage with major updates - unless you are comfortable auto-releasing every PR - and just QA the PR titles so that the release text is meaningful?

[TimothyJones]

commit-and-tag-version follows semver correctly - but below version 1.0.0, semver has no opinion.

Since we have to do something below 1.0.0, commit-and-tag-version follows the common convention of using minor (0.X.0) bumps for breaking changes, and patch (0.0.X) bumps for everything else. This is because that convention is used (and relied on) by common package managers like npm and cargo (cargo actually documented this, but for npm you can verify this with their semver calculator - eg with axios, ^0.1.0 will pick up only one package, but ^1.1.0 will pick up many).

[Maelstromeous]

Ah thanks @TimothyJones, in a "alpha" project like this one, what would you recommend? Simply going up to v1.0.0 then from then on use semver, or can the package be told to operate with a <1 version?

I've read the Conventinal Commits spec, and unless I'm truly losing my sanity it should be allowed with <1.0.0 to use say 0.2.0 -> 0.3.0?

[Maelstromeous]

@samsmithnz I've had a look at GitVersion before and it does what it says on the tin so to speak, but I do need it to do a bit more e.g. create a CHANGELOG.md which I don't believe that action does. I'm fairly happy for now to just manually update a /changes page on the site but I would like to automate that at some point. I'll also need to inject the git tag like I have in previous projects, requires injecting it into the build process or manipulating the config.ts file so the correct version can be rendered.

[samsmithnz]

I can help with this. I haven't done the automatic changelog piece, but I'm confident it's just another line in the GitHub action.

[Maelstromeous]

Thank you, any help on this would be very much appriciated as honestly my brain is trobbing on trying to make it work!

[TimothyJones]

Personally (even though I maintain commit-and-tag-version), I'd just use release-please for single projects with github actions.

It has some frustrating bugs with monorepos, but for single project repos it's very straightforward. I actually use it to release commit-and-tag-version - the action is here - you could just copy that in (and set the relevant secrets in your repo config).

The workflow is very straightfoward - first, make sure you're squash merging PRs (or, if not squash merging, then make sure you don't double up on changelog comments with the merge commit title). If there are user-facing commits, it will open a PR with the changelog, and when you merge that PR, the release will be automatically created. You can edit the content of previous PR bodies if you need to amend the changelog, too - I forget the syntax, but it's in their documentation somewhere.

---

unless I'm truly losing my sanity it should be allowed with <1.0.0 to use say 0.2.0 -> 0.3.0?

Sorry, yes - it's absolutely allowed (and encouraged) to use below 1.0.0 if your API isn't stable yet. However, technically every change is a breaking change below 1.0.0.

Most tools just treat 0.2.0 -> 0.3.0 as a breaking change, and assume that 0.2.0 -> 0.2.1 is not, though.

During initial development, I'd definitely stay below 1.0.0. This indicates that your API isn't solid yet, and lets you rapidly develop without worrying too much about breaking changes. Once you're relatively happy with the stability (or if you're making breaking changes less often), you can do a 1.0.0 release - and once you do that, you'll get the behaviour you were originally expecting with the version numbers.

[Maelstromeous]

Thanks for the insights @TimothyJones, very much appriciated. Hopefully we can work something out given the recommendation.

[samsmithnz]

Why is every change below 1.0.0 a breaking change? Is it because we haven't reached a major version yet? I've never thought about this before.

[TimothyJones]

It's just what semver says.

4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
5. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

It's very handy for initial development, where you're still figuring things out - and don't want to have to be at a high version number before many users have adopted it. For example, I've released 18 breaking changes to contract-case during the initial development - and it's nice not to be at version 19 for the first prime-time release (though it's pretty much ready for a 1.0.0).

[samsmithnz]

Got it. Thanks for the extra info. Learned something today! 🚀

[samsmithnz]

How do we want to handle this then. Auto-versioning (starting at version?) and auto-release (replacing the change log with the releases tab)?

• [ ] Version to start with
• [ ] Decision about change log vs releases tab

[Maelstromeous]

I think we can do both. I'm willing for now to simply have 0.0.x increments while we're in alpha stage, could follow the pre-release method of 1.0.0-alpha-prerelease1 and increment the release versions that way.

In terms of communications to the site, I think for now me having the Site Notice with a list of recenntly fixed bugs will do, until formalisation of official versions. After versions are sorted, we can then create a "changes" page, formally listing the versions and associated changes.

[Maelstromeous]

I'm working on right now of massively improving the formatting of the "top bugs and issues" notice the user sees when they first visit the site, which is dismissable. It also prompts the user to check it again via a manual change to the notice code, where if they've not seen that set of changes, it'll prompt them to look. #63

[samsmithnz]

GIven this isn't a public API, I think it's ok that every change is potentially breaking. The implication of starting with a 1.0.0-alpha release, is that it's more difficult to move to a 1.0.0 release. For example - imagine that in a few weeks/months, we might be at 1.4.23-alpha - it would be strange to go to 1.0.0. As an alternative, what do you think about starting at 0.5.0, or 0.8.0 or something?

[Maelstromeous]

We could also just treat 1.0.0 as the launch on Nov 16th and semver it from that, I don't particularly mind, users likely don't care about version numberings.

I think once we have these major bugs resolved I'm happy to call that "1.0", otherwise you're right, what is "1.0" and how could we get there? It would be a goal we'd be forever chasing.

[samsmithnz]

That works for me too! Let's do that, (start at 1.0.0)!

[Maelstromeous]

I'll work on this tomorrow - done a lot today so need a bit of a rest :)