Using `nbgv` without release branches and automatic semantic versioning

[julealgon]

I've been recently using this library/tool for managing versions on our apps, but there are still some aspects that are not fully clear to me.

Right now, we are using a very simplistic, automatic versioning, just so we have versioning at all, by having a version.json file like this:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.0",
  "publicReleaseRefSpec": [ "^refs/heads/master$" ],
  "cloudBuild": {
    "buildNumber": {
      "enabled": true
    }
  }
}

For now, this generates version numbers such as 1.0.14.51447, which work well enough for the current purpose.

However, this is obviously not how it was really intended to be used. For one, we never actually touch the version attribute in the version.json file, which is something that, as far as I understand, one is supposed to be doing every time there is an intent of releasing a new version.

Second, our number there is obviously not following semantic versioning (after all, we are never updating major or minor components), which is something I would like to start using, if we can do it without too much maintenance overhead.

But my main question really is in regards to our simpler branching structure. We currently try to use trunk-based development as much as possible, meaning we don't use "release branches" anymore. Instead, we just tag the commit with the release number and keep going on the master branch. The only time a release branch is created is when a hotfix is needed: then, a branch is created from the release tag, changes are performed there, and a new deployment pipeline is fired for the hotfix.

With these constraints/facts in mind, I'm a bit lost as to how I should be using nbgv to improve the way we are doing versioning. I don't really want the overhead of manually updating the version every time we have a new feature or a bug fix, since that would be basically every single change we make. Most of our projects are not libraries, but APIs, web apps, CLI apps, etc. Still, it would be very nice to have semantic versioning in place, so we could compare version numbers and know exactly what types of changes are involved (especially if there are breaking changes).

The first thing I was thinking about was using the prepare-release command with a computed versionIncrement value, based on "the commits since the last release", which would then give me an automatic way to compute the version number and remove the burden of manually setting that. But then I found out that prepare-release requires a release branch in the first place.

There is nbgv tag command which only creates tags, but that one doesn't have the versionIncrement argument, which makes it impossible to use for this purpose.

I feel like I must be missing something here considering how flexible and widely used this tool is. Surely trunk-based development with versioned API/Web projects is not that outlandish to not be doable properly?

In my mind, the ideal configuration would be to not have any version number declared on version.json, and have nbgv tag with support for versionIncrement as the main mechanism for "bumping the version". If this existed, and I could somehow compute what type of increment I needed given the list of commits since the previous release (this is not something I've done yet, but I'd like to automate it), then I could run this command after my deployment step and have that trigger a Github Release entry.

Apologies if this seems a bit confusing, it's just that I feel like I'm using this tool the wrong way at the moment, and I don't really know how to use it the right way considering our simplified deployment/release strategy.

[AArnott]

. I don't really want the overhead of manually updating the version every time we have a new feature or a bug fix

Oh ya, totally. That's the whole reason automated versioning should exist. I'm with you there.

it would be very nice to have semantic versioning in place, so we could compare version numbers and know exactly what types of changes are involved (especially if there are breaking changes).

The idea is that version.json is changed for semver events that are more significant than servicing. Breaking change: bump the major version, non-breaking feature addition: bump the minor version. Any other smaller change is a servicing fix and requires no version.json bump because we're just counting commits.

the ideal configuration would be to not have any version number declared on version.json, and have nbgv tag with support for versionIncrement as the main mechanism for "bumping the version"

I can imagine this happening two ways in your head, and I'm wondering which one you're imagining:

1. nbgv tag only adds a tag. The tag carries information about whether you consider it a major, minor, or servicing release event, and future version computations use tag information to determine what the version will be for a given commit.
2. nbgv tag does what nbgv prepare-release automates, in creating a commit that updates version.json automatically, and then tags the release.

Option number 1 is pretty much out of scope, because a core philosophy of NB.GV is repeatable, deterministic versioning for a given commit, and since can be added to a commit anytime after they are created, that would change the computed version for that commit and potentially all the follow.

Option 2 is very doable though. I'd probably just add a switch to nbgv prepare-release to allow for applying the new version to the current branch instead of creating a release branch. Although, that's very similar to what nbgv set-version can already do.

[julealgon]

Been a while since I posted this so bear with me...

. I don't really want the overhead of manually updating the version every time we have a new feature or a bug fix

Oh ya, totally. That's the whole reason automated versioning should exist. I'm with you there.

it would be very nice to have semantic versioning in place, so we could compare version numbers and know exactly what types of changes are involved (especially if there are breaking changes).

The idea is that version.json is changed for semver events that are more significant than servicing. Breaking change: bump the major version, non-breaking feature addition: bump the minor version. Any other smaller change is a servicing fix and requires no version.json bump because we're just counting commits.

I'm confused here. Aren't you contradicting yourself right there? If automated versioning is good, then it should not need manually touching version.json to update it, right? Or am I missing something there?

the ideal configuration would be to not have any version number declared on version.json, and have nbgv tag with support for versionIncrement as the main mechanism for "bumping the version"

I can imagine this happening two ways in your head, and I'm wondering which one you're imagining:

1. nbgv tag only adds a tag. The tag carries information about whether you consider it a major, minor, or servicing release event, and future version computations use tag information to determine what the version will be for a given commit.
2. nbgv tag does what nbgv prepare-release automates, in creating a commit that updates version.json automatically, and then tags the release.

Option number 1 is pretty much out of scope, because a core philosophy of NB.GV is repeatable, deterministic versioning for a given commit, and since can be added to a commit anytime after they are created, that would change the computed version for that commit and potentially all the follow.

Option 2 is very doable though. I'd probably just add a switch to nbgv prepare-release to allow for applying the new version to the current branch instead of creating a release branch. Although, that's very similar to what nbgv set-version can already do.

I think I'm basically doing option 1 now.

Since this post was made, I've went through several iterations on a couple of our repositories in terms of versioning and, currently, I'm doing the following:

Use nbgv as a means to carry the version into the assembly and to autogenerate tags (define the format only in a single place). The actual version value is never touched on the file: I'm basically ignoring it.

Then, during CI, I run a custom action that relies on https://github.com/paulhatch/semantic-version to parse all commits since the previous release and decide what version element should be incremented.

With the new increment, I use dotnet nbgv set-version to override the version for the current session, and then dotnet nbgv tag --what-if to obtain what the new tag is going to be for that version.

Later in the workflow, I create and push the tag using raw git tag and git push commands, and lastly create a release on GitHub using https://github.com/softprops/action-gh-release.

I still hate how I have to "partially" use 3 distinct tools to achieve this flow whereas I can find similar solutions in other ecosystems using just one tool (ran into GoReleaser multiple times while investigating options but never found such comprehensive solution in the .NET space).

It is just surprising to me that every single tool in .NET seems to be doing something custom and different while we all want very similar outcomes when it comes to versioning and releases:

1. Increment version automatically based on commits or change log entries
2. Tag releases automatically with the same version value on deployments
3. Work with trunk-based development
4. Create GitHub releases automatically with that same version using CHANGELOG.md

I also ran into the changie tool which appeared to be quite promising but had no easy path to be used from .NET.

And more recently, also stumbled upon this other, apparently obscure, .NET package https://github.com/ionide/KeepAChangelog which would finally sync CHANGELOG.md with the version in the project but doesn't solve the entire workflow.

It makes me incredibly frustrated to not find a good solution that covers all common aspects of versioning and releasing in .NET.

[AArnott]

I'm confused here. Aren't you contradicting yourself right there? If automated versioning is good, then it should not need manually touching version.json to update it, right? Or am I missing something there?

It's a dial, right? In the pure package.json world or any world without a versioning tool, you have to author a commit every single time you change the version, no matter how insignificant.
With NB.GV, you only have to update major.minor versions changes. Essentially, NB.GV can only divine from your git history that you made a change. It doesn't know how significant a change that is, so you help it along in that regard.
I think for most repos, a minor version bump doesn't come very often, and major version bumps are quite rare. That leaves most development free from thinking about version bumps, including day-to-day operations and potentially package pushes from your CI system to some feed. You're guaranteed the version is always unique. So ya, that's automatic.

The rest of what you're doing sounds clever and I'm glad you have a solution that works.

It is just surprising to me that every single tool in .NET seems to be doing something custom and different while we all want very similar outcomes when it comes to versioning and releases

The 4 item list you describe isn't as universal as you seem to believe. I think tagging with versions in the names and github releases to match is pretty universal. But incrementing versions based on changelog entries or by divining from commits the nature of the change and trunk-based development isn't all that universal.
Not to knock what you're doing at all. And what you describe may be quite common, I don't know.

There's another package called GitVersion that you might check out to see if it suits your needs better. It is willing to look at branch names and tags to inform its version calculation. NB.GV doesn't because those things are mutable, so one commit may be versioned one way today, and another way tomorrow although the commit itself hasn't changed.

I think for folks like yourself that are willing to commit (no pun intended) to following a strict system of how to title commit messages in order to avoid having to occasionally change version.json, what you want makes a lot of sense. Personally, I haven't seen broad enough adoption by people, repos, and tooling, to believe it's the majority of cases. And it certainly doesn't cover any case that I directly use. So between my own needs and that of the majority of users of NB.GV, I haven't seen a need to add or change the options that NB.GV offers out of the box. Although as you've discovered, I try to expose enough 'parts' that folks in your boat can custom build a solution that works for them.

I may yet come around. If I add something to cater more to your workflow, it would have to be an opt-in policy (which I expect you'd be fine with). I'd need to study more of what folks like yourself do (more than just you) to make sure what I add will add a significant segment to the potential users.

[julealgon]

Thanks @AArnott . I do understand your original intent with ngvb doesn't necessarily align with what we are doing right now. But as you said, I was able to make it work using the APIs you exposed so for now we are good. I actually didn't have a good enough solution when I originally posted this (which was one of the reasons why I did post it).

There's another package called GitVersion that you might check out to see if it suits your needs better. It is willing to look at branch names and tags to inform its version calculation. NB.GV doesn't because those things are mutable, so one commit may be versioned one way today, and another way tomorrow although the commit itself hasn't changed.

Yeah, I did run into it and actually tried it out (actually just a few weeks after I originally posted this issue) but ended up using nbgv over it as I ran into some issues (that I actually don't recall ATM). It might've been the lack of support for monorepos at the time, that caused some conflicts with what we were doing. The author of GitVersion has explicitly stated he does not intend to add support to monorepo scenarios with multiple independently versioned components etc.

I commented on this thread back then:

• Per-folder configuration for monorepo support GitTools/GitVersion#1268 (comment)

I might still eventually switch to using changie or a similar tool where version increments and release notes are more explicitly defined and not tied 1:1 with either commits, PRs or branches. If that tool was exposed as a native .NET tool, I would probably be using it by now. It solves another "area" that I don't like currently which is the automatic release notes from GitHub releases only picking PR titles by default and not being customizable enough. Changie allows more detailed, per-significant change, notes. Version increments and notes from changie plus version propagation/management from nbgv might be a good combo.

Leaving up to you if you want to close this issue now. From my perspective, you've clarified enough, and if there are further developments from it, it would probably make sense to spawn more specific issues for the individual features etc.

If you ever need more detail from our process (we do have a couple of different use cases currently in the company... there is this one here which we use for library repositories, and then there is a different one we use for our web applications/monorepo) just tag me.