Changelog is missing tags with almost-semver syntax

[slhck]

I am using v1.11.0.

I am generating the changelog for a project:

➜ auto-changelog
auto-changelog: 81 kB written to CHANGELOG.md

The changelog shows the following releases:

➜ grep "####" CHANGELOG.md | cut -d " " -f2 | cut -d "(" -f1 | head
[v0.52.1]
[v0.50.7]
[v0.50.6]
[v0.50.5]
[v0.50.4]
[v0.50.3]
[v0.50.2]
[v0.50.1]
[v0.49.8]
[v0.49.6]

However, some tags are completely missing:

➜ git tag --sort=v:refname | tail -r -n 10
v0.52.1
v0.52
v0.51
v0.50.7
v0.50.6
v0.50.5
v0.50.4
v0.50.3
v0.50.2
v0.50.1

I am completely missing v0.51 and v0.52. The tag exists, obviously:

➜ git show v0.51 | head
tag v0.51
Tagger: …
Date:   Mon Feb 18 12:37:53 2019 +0100

Tagging version 0.51

commit 98a186bcb9cd4ffcbd226535b8860f934c281aa7
Author: …
Date:   Mon Feb 18 12:37:53 2019 +0100

Any idea why these would be ignored by auto-changelog?

[slhck]

Oh, I see that this may be due to the tags not strictly following semver syntax, since v0.51 is missing the patch version. I wonder though if these should be considered nonetheless, seeing that also Git sorts them correctly with refname?

[ljharb]

Alternatively could you fix your tags to be the proper v0.51.0?

[slhck]

That's certainly possible, but it'd mean having to rewrite history and having all potential users prune old tags. Not saying that this is not possible, but it's a bit of an inconvenience.

That said, I see there is some handling of non-semver tags in https://github.com/CookPete/auto-changelog/blob/master/src/releases.js#L51 and that with a custom tag pattern this could be handled, which would be in this branch: https://github.com/CookPete/auto-changelog/blob/master/src/commits.js#L83

If I run with a custom tag pattern, the sorting breaks:

➜ auto-changelog --tag-pattern "\d+\.(\d+)?(\.\d+)?"
auto-changelog: 99 kB written to CHANGELOG.md

➜ grep "####" CHANGELOG.md | cut -d " " -f2 | cut -d "(" -f1 | head
[v0.52.1]
[v0.9.1]
[v0.9]
[v0.8]
[v0.7]
[v0.6]
[v0.52]
[v0.51]
[v0.50.7]
[v0.50.6]

[cookpete]

Using --tag-pattern is exactly what I was going to suggest, but releases with valid semver tags should be sorted properly according to semver.rcompare:

https://github.com/CookPete/auto-changelog/blob/e12a5404abfc1bfc76942286b22fa84d0d387439/src/releases.js#L46-L50

So this looks like a bug around that sorting logic.

[slhck]

I don't think so, since semver.valid() will (my guess) return false for v0.52, since it (strictly) should be v0.52.0. So instead, it sorts by simply parsing the float values, which means v0.52 is "older" than v0.6.

A good fix would be to change this line: https://github.com/CookPete/auto-changelog/blob/e12a5404abfc1bfc76942286b22fa84d0d387439/src/releases.js#L52

I'm not well-versed in the Node ecosystem; probably there's a package that properly compares these version strings but doesn't require strict semver compatibility.

[ljharb]

I’m sure you could normalize the semver strings - ie, add the missing dot zeros - but that still wouldn’t handle anything additional but “partial semver versions”

[slhck]

It'll actually be not as straightforward — if you get a string that is \d+\.\d+, you don't know if it's a major/minor/(patch) scheme, or just minor/patch.

I'm starting to think that the only real solution will be to stick to strict semver versioning.

[ljharb]

I mean, there’s literally no scenario i can conceive of where anyone would omit the major version - only trailing dot-zeros - but I’m also fine sticking to strict semver versioning since that’s the almost universal convention for non-multirepo git tags (and the universal suffix convention for multirepo git tags).

[cookpete]

I don't think so, since semver.valid() will (my guess) return false for v0.52, since it (strictly) should be v0.52.0. So instead, it sorts by simply parsing the float values, which means v0.52 is "older" than v0.6

Apologies – just me not paying close enough attention.

That's certainly possible, but it'd mean having to rewrite history and having all potential users prune old tags. Not saying that this is not possible, but it's a bit of an inconvenience.

You don't necessarily need to rewrite history. You could always add the correct semver tags at the same commits, then treat the incorrect tags as legacy/deprecated, and leave them for a certain amount of time before removing them?

I’m sure you could normalize the semver strings - ie, add the missing dot zeros - but that still wouldn’t handle anything additional but “partial semver versions"

I'm tempted to support this anyway as it seems to make sense. Given v0.50.7 and v0.51 you would expect it to be smart enough to know what came first.

[ljharb]

Maybe it could do that, but warn to stderr that nonstandard semver versions were found? That would help people catch this sooner.

[slhck]

You don't necessarily need to rewrite history. You could always add the correct semver tags at the same commits, then treat the incorrect tags as legacy/deprecated, and leave them for a certain amount of time before removing them?

You're right. That'd be a good alternative.

Thanks for considering supporting this additional format.

Maybe it could do that, but warn to stderr that nonstandard semver versions were found? That would help people catch this sooner.

That could be a possibility. Certainly I would've considered naming my tags differently had my changelog generation tool informed me (I was just using a rather simple script). Users should not be warned though if they use custom tag pattern.

[cookpete]

Partial semver tags are now sorted correctly as of 1.13.0, as long as they have the v prefix. eg v2 should now appear below v11 and v0.6 should appear below v0.54

[slhck]

That is awesome, thank you!