Feature suggestion: nbgv command to create a release branch

For some of my projects, I use the following branching model in conjunction with Nerdbank.GitVersioning:

• master always contains the latest development version, releases are built from a release/vX.Y branch
• master is always a prerelease version, so in version.json the version is set to e.g. 1.2-pre
• When a release branch is created, it is branched off from master and the prerelease tag is removed, while the version of master is increments. So in the above example, master would switch to 1.3-pre and a release branch release/v1.2would be created where the version is just 1.2

I wrote a small script to automate this process. However, I think this would be useful to be included as a command in the nbgv tool.

This way, creating a new release would be as simple as running

nbgv create-release

which would

• read the version from version.json
• create a release branch
• edit and commit new version.json on release branch
• edit and commit new version.json on master branch

Would you be open to include such a feature?
I would be happy to implement it and provide a PR.

[AArnott]

Should we prohibit some scenarios, e.g. adding a prerelease tag to a version that has no tag (effectively decrementing the version)?

At least printing a warning makes sense. We could block it and potentially allow it if -force was specified, but we don’t need to go to the trouble of supporting that before folks ask for it.

When including the git height in the tag, is the format always X.Y-tag.{height} or can the height be prefixed and suffixed with more tags? This could make setting the tag as part of the prepare-release command difficult

Yes, it can appear in multiple formats. My suggestion would be to simply add/replace the first prerelease identifier using the one specified at the command line. So -beta becomes -rc, -beta.{height} becomes -rc.{height}, -beta.{height}.foo becomes -rc.{height}.foo.

Regarding your scenarios, I’ll assume that all your vX.Y branch specs are based on a version.json file with:

{
  "release": {
    "branchName": "v{0}",
  }
}

Since if the branchName was release/v{0} then I presume all your branch name checks would be matching for the new pattern.

Regarding the transformation of the version on the master branch (or any branch that does not conform to the release branch pattern) as part of the command, I think we should add/change the first identifier of the -prerelease tag to be some constant, as defined by version.json. So the user can specify that any new version should start out as -alpha or -beta. So for examples (hint: these should become test cases, encoded as arguments to a [Theory]. I will assume that release.branchName = v{0} and release.firstUnstableTag = -alpha, release.versionIncrement = minor.

When run from any branch whose name does not conform to a release branch:

HEAD version	Command	New version	Created branch -> version
1.0-beta	prepare-release	1.1-alpha	v1.0 -> 1.0
1.0-beta	prepare-release rc	1.1-alpha	v1.0 -> 1.0-rc
1.0-beta.{height}	prepare-release	1.1-alpha.{height}	v1.0 -> 1.0
1.0-beta.{height}	prepare-release rc	1.1-alpha.{height}	v1.0 -> 1.0-rc.{height}

When run from a release branch, no branch is created, and the following truth table applies:

HEAD version	Command	Original branch version
1.0-beta	prepare-release	1.0
1.0-beta.{height}	prepare-release	1.0
1.0-beta	prepare-release rc	1.0-rc
1.0-beta.{height}	prepare-release rc	1.0-rc.{height}

From this we see that there are only 2-3 independent variables, that impact different things. So I hope this is a simpler model and simpler to code up than thinking about all the scenarios and their variants that you have listed.

[AArnott]

Perhaps what we can do then is have this new command accept an optional parameter that is the new unstable tag. For example, if master is building -beta then the prepare-release rc command will change -beta to -rc in the new branch. This makes the command generally more useful (since stabilization branches might not want to jump directly to building “stable” packages), and it also allows folks who move the git height to some prerelease tag to use the command as well.

When the command is invoked on a branch whose name already conforms to the release name convention, instead of branching, it simply changes the prerelease tag. So:

# version: 1.0-beta.{height}
[master]> nbgv prepare-release rc
# v1.0-rc branch created and version set to 1.0-rc.{height}
# v1.1-beta continues in master branch
[v1.0]> nbgv prepare-release 
# version.json in current branch is now 1.0 (-rc.{height} is removed)
[v1.0]>

Thoughts?