Prefix commit subjects with semver level

[gibson042]

TL;DR: Extend commit subjects to {semver-level} {Component(s)}: {Message}, e.g. minor Foo: Extend bar

I think we should include semver level in commit messages for ease of hotfixing/releasing/cherry-picking/etc. And since it seems to be even more important than the affected component(s), I'd like it not just in the subject but at the start of the subject. I've opened jzaefferer/commitplease#44 to extend the configurability of commitplease for making such changes easier, which serves double duty as my proposed format.

I'd like to reserve this issue for bikeshedding the details of the subject requirements, and jzaefferer/commitplease#44 for figuring out how to express them.

[Krinkle]

Node.js has been using more the verbose (SEMVER-MINOR) and (SEMVER-MAJOR) in their commit messages.

For example: https://github.com/nodejs/node/blob/v5.0.0/CHANGELOG.md#commits

Commits

• [1a41feb559] - buffer: don't CHECK on zero-sized realloc (Ben Noordhuis) #3499
• [5f6579d366] - (SEMVER-MAJOR) buffer: remove raw & raws encoding (Sakthipriyan Vairamani) #2859
• [870108aaa8] - (SEMVER-MAJOR) console: sub-millisecond accuracy for console.time (Michaël Zasso) #3166
• [680dda8023] - dns: remove nonexistant exports.ADNAME (Roman Reiss) #3051

[scottgonzalez]

I don't really want to implement this in any of the projects I manage.

[mgol]

Node.js has been using more the verbose (SEMVER-MINOR) and (SEMVER-MAJOR) in their commit messages.

Click in the links you pasted, there is no SEMVER-* there. They seem to be retroactively added when constructing the changelog for a release, they're not included in commit messages.

[gibson042]

Semver level is the most important detail of a commit, because it dictates the versions allowed to include it. That's why I want it in the subject. If we're worried about space, I'd advocate moving component(s) into the body first, since they take up even more (especially if a commit affects multiple) and seem most useful for changelog generation, which requires the full body anyway.

Regardless, though, git log [--grep] can support any rational scheme. The point is to start capturing this information, and I'd prefer to do so consistently (hence the issue).

[markelog]

This information could be useful for changelog generation btw.

I don't think you can validate all commits this way, like misc, docs, etc; if such changes are not released with the project, they pretty much have nothing to do with semver terminology and because it would complicate contributing process for the beginners even more - it seems this responsibility should be on the maintainer, like sign-off tags.

I also don't think it should be requirement for everyone, team of any project should decide for itself.

I also wouldn't refuse to see example of the project with similar guide line.

[dmethvin]

I see the point @gibson042 makes about the semver level being more important than the component. It's not hard to see what component(s) are affected by a commit but you really have to understand the code that was changed to know its semver impact. Still, the first line of the commit is already pretty crowded so I'd prefer to see this info in the commit body as @leobalter suggested.

I wonder how the Node folks determine the semver level, it doesn't seem to be described in the commit so I guess they must review and determine it ex post facto.

[jzaefferer]

Semver level is the most important detail of a commit, because it dictates the versions allowed to include it.

Can you explain how to expect to make use of this information?

Without more information, I agree with Scott - the commit message seems to be the wrong place to make any decisions related to backwards compatibility. For both QUnit and jQuery UI we spend a lot of time planning gradual migrations to introduce new features and remove old, commit messages were never part of that process.

Since you mention cherry-picking, maybe this is very specific to Core, with two stable releases managed in the same repository?

[rxaviers]

FWIW, I liked the idea of including semver info in the commit message, but my vote goes in line with what Leo and Dave suggested: in the commit body.

[scottgonzalez]

Since you mention cherry-picking, maybe this is very specific to Core, with two stable releases managed in the same repository?

There's honestly no difference between what Core does and what UI does in terms of managing multiple branches for parallel version releases. And api.jqueryui.com has an even larger spread of cherry-picking (historically it has been fairly common to cherry-pick commits across every version).

[leobalter]

This semver idea is great. Flagging commits to tell my next version is great, and it involves a change log generation, where the message title can be prefixed, as in Node.

In the commits it can still reside at the body like I suggested earlier in a private email: "Semver: Major"

This is also very useful to determine my next npm version.

This message standard would be of a great value to QUnit and its release process.

[mgol]

@jzaefferer

Since you mention cherry-picking, maybe this is very specific to Core, with two stable releases managed in the same repository?

This has nothing to do with us having two parallel branches. This is a result of us wanting to not release jQuery Compat at all and instead release 1.12 & 2.2 that will have non-breaking changes backported from compat & master respectively (and stop cherry-picking to compat afterwards). We need to identify commits that introduced breaking changes so that we don't backport them.

[jzaefferer]

We need to identify commits that introduced breaking changes so that we don't backport them.

Shouldn't it be obvious enough when reviewing a patch to land in master if it can also land in another branch? The odds of landing breaking changes in master without a lot of scrutiny should be extremely low anyway.

I currently don't see the advantage of annotating commits with this information, when its is not relevant anymore after the commit landed in one or more branches.

[mgol]

Shouldn't it be obvious enough when reviewing a patch to land in master if it can also land in another branch?

This is not the situation we're in. We already have ~300 commits on master that are newer than what's in the latest 2.1 release. They're there and some of them are breaking changes. We didn't pay that much attention as to which ones were breaking as we assumed they'll make it into jQuery 3.0.0 which will be a major release that's allowed to introduce breaking changes. Now we need to backport some (or most, to be decided) of those ~300 commits to jQuery 2.2.0 (and another ~300 commits from compat to 1.12.0) but without a way to quickly filter out the breaking ones we need to carefully examine every single one of them which is more time consuming.

[scottgonzalez]

Honestly, you should be examining them anyway. I think it's fine to define a standard for projects that want to use it. Since commit guidelines aren't requirements for all projects anyway, I'm trying to mostly stay out of this discussion since I don't want to implement this in the projects that I manage. But I don't think auto-porting 300 commits without manual review is a sane thing to do even with this additional information.

[jzaefferer]

This seems more of a workflow or process issue then.

We didn't pay that much attention as to which ones were breaking as we assumed they'll make it into jQuery 3.0.0 which will be a major release that's allowed to introduce breaking changes.

That sounds scary. I wouldn't want to deal with that at all, no matter what the commit message claims. Even with a 3.0.0 release, how are you dealing with migration issues? Are you working on an upgrade guide already?