Insight into Octoversion

Hi folks,

I am looking at using Octoversion in favor of Gitversion to ease some of my versioning pains, and I was wondering if you could share how your teams use Octoversion internally? In particular, how it interplays with your tagging strategy on main, and if you have any repository rules like requiring tags on particular branches, etc.

When I began using it in a test project, I had a main branch and a branch called test. I had a tag on main with a value of 1.0.0. When I committed to the test branch I saw the versions incrementing like 1.0.5-test, 1.0.6-test, and so on. When I merged test to main I guess I was expecting the version to be 1.0.7 but it was instead 1.0.1.

I would guess that you have some sort of rule or convention that if you merge to main you would increment by an entire minor version number (a la 1.1.0 after 1.0.0) but I thought I’d ask the authority. :smiley:

Thanks in advance for any insight you can give, and if it matters, I have a paid license.

Best regards!

Hi @arcain,

That’s a good question. I am going to ask one of our engineers to make sure I am getting that right. It might be a bit before I can get back to you.

Greetings @arcain

You were pretty much on the right track with your example and what you thought should happen! In the case you outlined, our merge to main would indeed be tagged as 1.0.7

Did you squash or merge the PR? If you “merged” the PR then I would expect the default “commit counting” behaviour to have arrived at 1.0.7 (as it would be 7 commits since the last tag of 1.0.0 in the commit history as the 6 commits from your PR are part of the history). But many people prefer to SQUASH their PR to keep the target branch with a cleaner history… and in the case of squashing, you WOULD get 1.0.1 (since there is only 1 commit since the 1.0.0 tag - the 6 commits on the PR branch are not part of the commit history of the squash merge on main).

So in order to suppport our engineers squashing or merging as they see fit, we want to avoid automatic behaviour like commit counting and be EXPLICIT about our patch number. This can be done via cmdline argument (--Patch) or by setting env var (OCTOVERSION_Patch) prior to executing OctoVersion. In TeamCity, the variable we use is %build.counter% and in GitHub Actions we use ${{ github.run_number }}. Most CI systems should have an equivalent mechanism.

This gives us an ever incrementing patch number that is always larger than a previous build. If you look closely at our download archives, you will see that the counter is not specific to a major/minor release but is a constantly incrementing number. As long as a newer build has a larger build number, we dont particularly care if there are “gaps” in the patch numbers.

Other than that, we typically include an octoversion.json file in the repository root containing the following setting which controls which branches receive pre release tags and which ones don’t (main, master and any release branches eg release/1.0

  "NonPreReleaseTagsRegex": "refs/heads/(main|master|release/.*)"

So… TLDR! :laughing:
We pass CurrentBranch and Patch to OctoVersion from the CI platform and use the above octoversion.json file checked into the repo, to control the branch pre release rules.

Hope that helps!

Ah ha, that makes sense. Yes, I was squashing the living daylights out of the branches, but the missing part was supplying patch in one form or another. I cribbed the octoversion.json config from one of your repos, so I have that in place, and that works like a charm. Thank you Ryan for the detailed write-up, it was very helpful! And thank you too Bob!

1 Like