tag suggestions

[sam-wheat]

I'm still learning nbgv - a couple suggestions related to tag:

It seems a command like tag [major|minor|patch|pre] would be useful. If version.json says version is 1.2.3-alpha tag pre would bump it to 1.2.3-beta and create a tag with same name.

tag promote <tagname> seems useful also. tag promote 1.2.3-alpha would create 1.2.3-beta based on 1.2.3-alpha. I imagine there will be some limitations around this but the essence of the command is to create tag B based on tag A.

These suggestions are based on workflow described here. As mentioned I'm still learning. If I'm anywhere close to the mark I'll make a feature request.

[AArnott]

Thanks for your feedback and ideas.

It seems a command like tag [major|minor|patch|pre] would be useful. If version.json says version is 1.2.3-alpha tag pre would bump it to 1.2.3-beta and create a tag with same name.

I hesitate to create a tag sub-command that would do more than tagging. And in fact the behavior you describe would require authoring a new commit in order to tag it with the new prerelease identifier.

but the essence of the command is to create tag B based on tag A.

I don't see value there, seeing as this is already trivially easy with git tag 1.2.3-beta 1.2.3-alpha.
But it would probably be misleading to do this anyway, because that commit will still build 1.2.3-alpha, since -alpha is in the version.json file. Promotion would require a new commit that changes the version.json file.

We already have nbgv prepare-release that does at least some of what I believe you're thinking. If it doesn't do prerelease promotion, I'd say that's probably the command I'd enhance rather than tag.

[sam-wheat]

Right, I should not specify how it should be implemented:

As a nbgv user I would like to be able to tell nbgv to create a tag on my behalf and that the new tag will represent a [major|minor|patch|pre] increment in the current version. This will allow me to not have to use magic branch names and will also allow me to create tags without knowing what the current version is.

And in fact the behavior you describe would require authoring a new commit in order to tag it with the new prerelease identifier.

Understood.

As a nbgv user I would like to be able to create a new tag based on an existing tag and have nbgv promote the pre-release section of the version identifier. Thus 1.2.3-alpha will become 1.2.3-beta, and 1.2.3-beta will become 1.2.3.

Promotion would require a new commit that changes the version.json file.

Understood. In our workflow we promote builds which is to say we (effectively) copy binaries from one environment to the next. We use a build as a glorified way to copy files. Addition of correct version metadata is desirable.

We already have nbgv prepare-release.

prepare-release does not really fit into our workflow. Most notably we don't create branches for releases.

I very much like the thought process behind prepare-release. I have more to say about this but it is somewhat of a tangent.

[AArnott]

This will allow me to not have to use magic branch names

NB.GV doesn't do magic branch names (like another git-based versioning tool is). Branch names have only one small impact on the version, and version numbers and alpha/beta isn't a part of that.

will also allow me to create tags without knowing what the current version is.

I'm very curious about your use case for this. When would you want to create a tag without knowing the version? You've already discovered nbgv tag, which does exactly this, but the tag is exactly based on that commit's encoded version. It doesn't change the version.

Most notably we don't create branches for releases.

I'd like to understand your release creation process more.
My own workflow tends to be that once a release is done, I change version.json to reflect the upcoming release. But if you only use tags, and you expect nbgv to author a commit to update version.json and tag in one step, that suggests that the whole time you're developing your -beta release, it's building with an -alpha tag. In my workflow I build -alpha while working on -alpha. Then when we're satisfied that we're now in -beta quality, I change version.json while we continue to work on -beta. When we're ready for a -beta release, we can nbgv tag that commit and proceed with -beta.2, or -rc, or whatever.
What I think is the critical difference in our workflows is that I change version.json during development to match what's being developed, and I think you change it to reflect what you've been working after development is done. Is that right? And is your ordering important to you?

[sam-wheat]

Hi Andrew, thanks for your comments. I went back to prepare-release documentation and it made more sense to me.

What I think is the critical difference in our workflows is that I change version.json during development to match what's being developed, and I think you change it to reflect what you've been working after development is done. Is that right?

Yes.

And is your ordering important to you?

I think so - there are some things I still don't understand:

I change version.json to reflect the upcoming release.

Not sure I understand this - documentation says "If the version on the current branch is..." If version.json holds the id of the next release, how does nbgv know the version of the current branch? These two statements also seem to indicate that the version in version.json is not the next one:

"Remove the prerelease tag from version.json on the release branch"

"Back on the original branch, increment the version as specified in version.json."

I read a statement in the documentation of a different versioning tool. It says something like "Semantic Versioning is all about releases, not commits or builds. This means that the version only increases after you release". Ironically, this pearl of wisdom helped me realize why the approach taken by nbgv is the correct one. By correct approach I mean that prepare-release offers the developer the opportunity to do versioning after development is done (regardless of whether version.json points to current or next release).

My thought process is that determining the next version the instant before the binary is actually created gives me complete control over what the next version will be, and it frees me from needing to add any magic to my branching/tagging (but these may be non sequiturs as you have mentioned). Your points about version.json pointing to next version make total sense but what if, at the last moment, you decide your release is going to be 1.1.0 and not 1.0.1 as you first thought?

Also, I want to back up a bit and explain our use of tags: We only create tags when we release. We don't have versions so we use folder names and those folder names match our tag names. My goals in implementing versioning are:

Every binary .exe that is released is uniquely versioned
Every version points to a tag on our repo that is of the same name.

This is why I am requesting the tag functionality. I want the existence of a tag to be a prerequisite to kicking off a build and the build must build off the tag. I suppose we could use a branch but I really like the idea of tag immutability.

When would you want to create a tag without knowing the version?

As a convenience, eliminate typos, and use within a script to allow nbgv to be the single source of truth.

[AArnott]

version.json describes the current version of that commit. It doesn't express some future version, nor some past version. If you want a particular commit to build v3.4 of your software, you need that commit to contain a version.json that says "version": "3.4" in it.

During development, whether version.json carries the same version that you shipped before or the version you anticipate shipping doesn't matter so much, since you haven't released it yet. Certainly though by the time you release, you should make sure that version.json contains the version you intend to release. If it doesn't, you have a commit to author to change the version in that file.

Every commit will build a unique version, because the commit feeds into the version system. If you specify 3.4 in version.json, the commit info feeds into the next two numbers, such that the exe you build may have version 3.4.123.23582. Even as you develop, each commit will produce a unique version. So you don't even have to bump from 3.4 to 3.5 from one release to the next, because it will naturally progress from (e.g.) 3.4.123.23582 to 3.4.128.19234.

And if you want to tag a commit, just use nbgv tag and it will tag your current commit with a version that matches the version that that commit would produce.

I would not tag every commit that ever built. That'll result in roughly every commit having a tag, which seems extremely noisy. Hopefully by tagging releases you mean real, public releases which are few and far between. That makes sense.

You know you can also use nbgv get-commits 3.4.128.19234 to find the commit behind a version, even without tags.

[gcadmes-extron]

Hi @AArnott ,
I'm learning nbgv as well.
QQ for you.
Is it possible to remove the 'g' and commit id from the package filename?
Ideally from this:

My.Company.Name.1.10.0-release-g19fa2ea175.nupkg

To this

My.Company.Name.1.10.0.123456.nupkg
thank you

[AArnott]

@gcadmes-extron the -gCommitId suffix is added when the PublicRelease value is false. You can set the default calculation for this in version.json via the publicReleaseRefSpec property. But you can override it on a per-build basis by setting the msbuild property by the same name yourself (possibly as a global property).
But your example did more than your question: it also removed -release from the version. Stripping a prerelease tag like that off the version is designed to be done by removing it in your version.json file. Anything besides that requires more direct msbuild property manipulation between the GetVersion target and the consumers of the properties that it sets.