Add support for indicating change severity in commit messages

[TomGillen]

Adds two new increment strategies: CommitMessage and MergeMessage.

While active, the version increment is determined by reading commit/merge commit messages for markers describing the change severity. All new commits introduced since the base version are scanned.

For example, "+semver: breaking" will force a major version bump.

New Branch Configuration Options

• major-version-bump-message: a regex used for parsing breaking changes in commit messages. Defaults to \+semver:\s?(breaking|major).
• minor-version-bump-message: a regex used for parsing minor changes in commit messages. Defaults to \+semver:\s?(feature|minor).
• message-fallback: the increment strategy to fall back into if no change severity indicators are found in commit messages, while using the CommitMessage or MergeMessage strategies. Defaults to Patch.

Potential Issues

• I changed the default increment strategy for the master branch to CommitMessage. This will behave the same as it did prior to this change if the user does not have markers in this commit messages. However this could certainly be considered a breaking change.
• This change does not work for new repositories, as the base version of a new repository will be determined by the FallbackBaseVersionStrategy, which never increments versions. Certainly, If I am using GitHub Flow, this is not what I would expect. Changing the behaviour of FallbackBaseVersionStrategy when using commit message increments would be an option, but I do not know if this would make sense for other work flows.
• Breaking changes always increment the major version. This may not be desirable for < 1.0.0 builds. We could add an option to treat breaking changes as minor version bumps for 0.x.x builds.

Addresses #137.

[JakeGinnivan]

Nice, I will hold off on this until 3.0 has been released (which should be soon)

[TomGillen]

I've rebased onto master after the 3.0.2 release. I would like some feedback on those potential issues before a merge, though.

This also still needs some unit test coverage.

[JakeGinnivan]

Awesome, will look through it later today.

[JakeGinnivan]

Sorry for the delay, just started back at work last week since moving back to Australia.

Rather than changing config I think that maybe we change the increment strategy to have something like this (obv this code would not compile/work, but hopefully give you the idea)

public static VersionField DetermineIncrementedField(GitVersionContext context, BaseVersion baseVersion)
{
    var incrementFromCommitMessage = FindIncrementsFromMessagesSince(context, baseVersion.Source); //baseVersion.Source is the commit used for commit counting, it is a good from filter of the commits we need to scan
    if (incrementingCommitOrMergeMessages.Any()) {
        var max = incrementFromCommitMessage.Max();
        var configIncrement = SimpleIncrement(context.Configuration.Increment);
        return (max >  ? max : configIncrement);
    }
    return SimpleIncrement(context.Configuration.Increment);
}

This way we don;t have to update any config, it will just light up?

[JakeGinnivan]

This change does not work for new repositories, as the base version of a new repository will be determined by the FallbackBaseVersionStrategy, which never increments versions. Certainly, If I am using GitHub Flow, this is not what I would expect. Changing the behaviour of FallbackBaseVersionStrategy when using commit message increments would be an option, but I do not know if this would make sense for other work flows.

If we use my approach the commit messages override the increment from the config, solving this issue

[JakeGinnivan]

Actually, I think my approach fixes all the issues listed under potential issues?

What do you think?

[TomGillen]

You are essentially proposing that we always respect commit message severities, rather than have the user specify it via new increment strategies. I have no particular objection to this, but it does not fix all of the problems.

This code overrides the normal increment strategy when it finds relevant commit messages. However, the increment strategy is ignored entirely if the version strategy returns a BaseVersion with ShouldIncrement set to false. The FallbackBaseVersionStrategy always does this, and as such commit messages will never increment the version while that strategy is in effect (e.g. a clean repository with not yet any releases). Is this expected behaviour? As soon as the user does something which changes the version strategy (e.g. tags v0.2.0), commit messages will begin to affect the version number.

There is also still the issue of alpha (< 1.0.0) versions. There could easily be many commits tagged as breaking changes, but many users would not expect their version to be bumped up to or beyond 1.0.0 automatically. We could maybe do with having an option to treat breaking changes as minor version increments while the base version is < 1.0.0.

[JakeGinnivan]

However, the increment strategy is ignored entirely if the version strategy returns a BaseVersion with ShouldIncrement set to false.

If we made this strategy always run before the normal increment code. If it finds an increment message then it increments the version, even if the branch setting says not to.

There is also still the issue of alpha (< 1.0.0) versions

Agreed, if the version we are incrementing is < 1.0 we should just bump minor instead.

[JakeGinnivan]

What do you think @thogil?

[TomGillen]

Sounds reasonable. I'll have a look at updating the PR later today.

[TomGillen]

The code now looks for major, minor and patch commit messages. If it finds one, it will use that increment, regardless of the base version ShouldIncrement property.

There are branch configuration values for the three message regexes, which default to:

1. \+semver:\s?(breaking|major) e.g. +semver: breaking
2. \+semver:\s?(feature|minor) e.g. +semver: feature
3. \+semver:\s?(fix|patch) e.g. +semver: fix

There is also a commit-message-version-bump-mode setting, which controls which messages are read. It defaults to All, but can also be MergeMessageOnly or None (disable this feature).

If no commit message increments are found, it falls back to the default behaviour. If the version would have been incremented by branchConfig.Increment, had there been no commit messages, then it will always increment by at least branchConfig.Increment. It is also capped at minor for versions < 1.0.0.

[TomGillen]

@JakeGinnivan I don't know why the AppVeyor build is failing. The only thing which looks like an error is coming from Fody, but that error also exists in the (passing) master build. The build just appears to halt silently.

[JakeGinnivan]

I'll check it out tomorrow

Sent from my Windows Phone

---

From: Thomas Gillenmailto:[email protected]
Sent: ‎18/‎08/‎2015 6:51 PM
To: GitTools/GitVersionmailto:[email protected]
Cc: Jake Ginnivanmailto:[email protected]
Subject: Re: [GitVersion] Add support for indicating change severity in commit messages (#489)

@JakeGinnivanhttps://github.com/JakeGinnivan I don't know why the AppVeyor build is failing. The only thing which looks like an error is coming from Fody, but that error also exists in the (passing) master build. The build just appears to halt silently.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/489#issuecomment-132170377.

[JakeGinnivan]

This config shouldn't be per branch I don't think? Can it be pulled up to root?

[TomGillen]

Yep, sure.

[SimonCropp]

try updating to https://www.nuget.org/packages/Visualize.Fody/0.4.4

[JakeGinnivan]

Do we need this to be configurable per branch?

The default should be set at the root level, you can leave it configurable per branch but it should be an override to whatever is specified in the root

[JakeGinnivan]

Awesome!

One more thing, you are going to have to rewrite history to remove For example, "+semver: breaking" will force a major version bump. from your commit message :P we are currently building v4.

So it works :P

[TomGillen]

Oh, good point ;)

[JakeGinnivan]

I am heading out now. I have just put up a PR myself. This will be in 3.1 which should be released tomorrow/saturday

[JakeGinnivan]

Thanks for this, its an awesome addition!

[JakeGinnivan]

Really should have added docs for this.. didn't think about that at the time, now I am doing the release thinking we should have.. I might put initial docs in then move the tag :P

After I have put the initial docs in if you want to review/add anything feel welcome to