Naming of Releases Branches and Release Tags

[robertosfield]

Hi All,

Last week I did some testing with the GitHub auto-generated release tarball and was a bit suprised that the downloaded tarball names and unpacked directory were in the form VulkanSceneGraph-VulkanSceneGraph-1.0.4, rather than the VulkanSceneGraph-1.0.5 I was expecting. The release tarballs/zip can be found at:

https://github.com/vsg-dev/VulkanSceneGraph/releases/tag/VulkanSceneGraph-1.0.4

I looked to see if there was a way of hinting to GitHub releases generation to not use the githib project name as a prefix to the release tag but haven't found a way to resolve it. The best I could divine is that github recommend Semantic version with out without v prefix and nothing else. The docs are:

---

Tagging suggestions

It’s common practice to prefix your version names with the letter v. Some good tag names might be v1.0.0 or v2.3.4.

If the tag isn’t meant for production use, add a pre-release version after the version name. Some good pre-release versions might be v0.2.0-alpha or v5.9-beta.3.

Semantic versioning

If you’re new to releasing software, we highly recommend reading about semantic versioning.

A newly published release will automatically be labeled as the latest release for this repository.

If 'Set as the latest release' is unchecked, the latest release will be determined by higher semantic version and creation date. Learn more about release settings.

---

So I've already been following the semantic versions but not the minimal prefix by using VulkanSceneGraph-1.0.x for the tags rather than 1.0.x or v1.0.x. In hindsight I would have adopted either 1.0.x or v1.0.x as a convention had I been aware that there was this convention built into the GitHub release scripts.

I've like to avoid the goofy VulkanSceneGraph-VulkanSceneGraph-1.0.4 naming as it just doesn't feel slick or professional, so have begun experimenting with changing the vsg_add_option_maintainer(..) macro in cmake/vsgMacros.cmake to allow us to pass in prefix without appending an - to it. This means the usage changes from :

vsg_add_option_maintainer(
    PREFIX VulkanSceneGraph
    RCLEVEL ${VSG_RELEASE_CANDIDATE}
)

To (note the addition of the - after VulkanSceneGraph)

vsg_add_option_maintainer(
    PREFIX VulkanSceneGraph-
    RCLEVEL ${VSG_RELEASE_CANDIDATE}
)

This gives us the same VulkanSceneGraph-1.0 branch and VulkanSceneGraph-1.0.x release tag naming we've already had. This is is a first step, but it will require me to update the projects like vsgXchange, vsgQt, vsgImGui to add the - like above to keep working the same way.

This change is just the first step though, as potentially we could now adopt the "" or "v" prefix so would get a 1.0 or v1.0 branch name, and 1.0.5 or v1.0.5 tag name for the next release.

I'm torn between v1.0.x and just 1.0.x for releases so I will have a look at what other projects that the VSG projects depend upon to see which conventions they have gravitated towards. I'd like the VSG to just fit in to what people are most used to.

Once we've decided upon the convention for the VSG itself I'll roll out this change to the other projects within the VSG family. I will also need to decide what to do about the existing VulkanSceneGrasph-1.0.,x release tags and VulkanSceneGraph-1.0 branch. My inclination is to go back and renamed them to keep everything consistent.

The downside with renaming existing tags is that if there are 3rd party projects that depending upon a fixed URL and release name. I'm hoping that just changing to a new convention for all tags will just require existing scripts to be updated once and they they'll not have to come up with any pre 1.0.5 (which will be our next release) with the old naming, or there after with the new convention. Given it was back in November we had our first stable release I'm hoping that few will have made a hard links so this will be be a non issue.

Before I make a final decision on the naming I'd really like feedback from the VSG community to what you are used to/what your preferences are, essentially do prefer:

• {major}.{minor}.{patch} i.e. 1.0.5
• v{major}.{minor}.{patch} i.e. v1.0.5

Cheers,
Robert.

[robertosfield]

Looking at other projects that vsgXchange depends upon:

---

Assimp uses the v{major}.{minor}.{patch} convention:

https://github.com/assimp/assimp/tags

https://github.com/assimp/assimp/releases

---

curl does what the VSG project has been doing, and naming the release tag with the curl-{major}.{minor}.{patch} convention and has the same problem with the double named directories:

https://github.com/curl/curl/releases

$ ls
curl-curl-8_0_1  curl-curl-8_0_1.tar.gz

So... at this point I think going with v{major}.{minor}.{patch} would at least fit in with assump.

[robertosfield]

And glslang just uses {major}.{minor}.{patch} and a few other variations through in as well:

https://github.com/KhronosGroup/glslang/tags

"The great thing about standards is that there's so many to choose from!"

[robertosfield]

I have done some clean up work on the cloning of glslang using cmake and created a 1.0.5 release candidate:

https://github.com/vsg-dev/VulkanSceneGraph/releases/tag/v1.0.5-rc2

[vsg-dev]

I have now tagged the VulkanSceneGraph-1.0.5 release using the v1.0.5 tag, I'll leave it in place for a few days before I make any changes to the naming of the other tags. My thought is to renamed the VulkanSceneGraph-1.0.x tags to v1.0.x to keep everything consistent.