Users / Customers have asked about support for semantic versioning in GitLab. We currently do not have native support. However, one way forward before we can build it into GitLab, is documenting how to integrate with the open source package semantic-release to enable semantic versioning for releases.
Further details
Proposal
Create a section in our documentation that references the semantic-release package and provides a guide on how to implement it.
Aside from the lacking of the native SemVer support [1], semantic-release is one of the most popular tools to orchestrate releases. They have a plugin [2] for GitLab CI/CD so that users can easily bring the Conventional Commit [3] into their practice . We also provide a tutorial [4] for this usage.
Just an FYI that "There is a Guided Exploration for that." [1]
The most sophisticated, automated handling of sem version "next version determination" to many active branches in a busy repository that I've see is GitVersion. This Guided Exploration (working example) shows a GitLab CI Plugin Extension for using GitVersion with any project. It demonstrates using the generated version numbers for containers and two packaging formats and uses release-cli to create a release.
Interestingly, the last version number does not need to be persisted anywhere because GitVersion employs a variety of techniques to "discover" the last or current version number from branch names, tags, etc.
GitVersion has a lot of default behaviors but is also highly customizable per-branch.
It also demonstrated GitVersion automatically updating a repository-wide non-duplicated version number as you merge through your gitflow - Feature Branch => develop => main => release.
It is implemented as a CI / CD extension so can be included into other projects fairly easily.
It does a fancy dance to see if you have a "GitVersion.yml" in the source repo and retrieve it at the right time.
@shinya.maeda@skamani@DarwinJS - What's the best way of addressing customers' needs? It seems we have several documented examples of using semantic-release to meet the requirements. The question now is, should this be added to the documentation, or presented as a blog post? Although a blog post would deliver the necessary information, blog posts are not maintained, so may become outdated. If we add this to the documentation, it would be more likely to be maintained. Also, in the documentation we could tie this into the GitLab toolset. Perhaps we could publish it as tutorial (see https://docs.gitlab.com/ee/tutorials/ for examples). What do you think?
CC @cbalane - FYI. I set this issue's milestone to %14.9, but I doubt I'll be able to deliver anything in the docs within that milestone. I think we're at the research stage. What priority would you assign this issue?
@rdickenson It seems we already have the documentation. This has a good coverage on how to setup the tool. Maybe we can cross-link to the doc from Release index.md for the starter?
IMHO, semantic-release is too good to hide away to the less visible sections
If that is the official documentation I would suggest it should be implemented as a plug-in extension (built as an include) that passes the resultant pipeline into the rest of the pipeline using a .ENV file.
Otherwise folks are likely to think it is NPM specific, rather than usable with any language if all it does it output a pipeline variable.
Since the Guided Exploration handles the most complex case and many folks may not need it that complex - perhaps citing both - the npm one as a simple case and for complex or busy repos the GitVersion example?
@rdickenson - that is correct! Have it emit a pipeline variable with the new version and then anyone using any language frameworks can utilize the result.
Even then, it is important to call out that the example is not NPM specific.
This is where the CI/CD extension implementation for GitVersion emits the intelligently determined version number for the rest of the pipeline(s) to consume in various flavors:
@DarwinJS - In these examples, what's the most important point to be highlighted, or explained? From my understanding, it seems the "intelligently determined version number" is key.
@Russell - I believe that if the example is not explicitly designed and commented that it is for usage with any language or pipeline, that our minds do a mental shortcut to thinking we need to find a version of this for the language / platform our application is written in.
In fact, that is reinforced by experience with shell runners where installing another entire framework like NPM just to generate a version number for something like a python app may undesirable due to creating an even more complex CI Builder stack.
So requirements would be:
ensuring the implementation supports any technology by passing the determined version number a variable(s) in a .ENV file (shown more simply here)
@DarwinJS - I've read the examples linked in this issue and have to admit that I'm struggling to understand them.
It seems to me that use of GitVersion would be best, given it's dynamic. Beyond that, I'm not sure where to go from here. If I understand correctly, we could recommend use of the techniques demonstrated in your GitVersion demo [1]. That acts as a CI/CD plugin, and outputs a Semantic Versioning-compliant version number, using the dotenv artifact. A subsequent job in the pipeline, typically a build job, inputs the version number from the dotenv artifact and uses that to define the release number. Is my understanding vaguely correct?
Is there a simple example project in which we could demonstrate this technique?
@rdickenson - that repository is a working example as well.
Here is the challenge - GitVersion is targeted to solve the most difficult challenge and so suffers a bit from downscaling to simpler requirements. My example is relatively simple.
The worst case, with best practices, is that EVERY feature branch pushes "production candidate" packages to a package or container registry so that those artifacts can be tested. When an artifact passes all tests it is then deemed releasable. According to https://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912 - these artifacts should NEVER be rebuilt.
So if all those branches need a unique version number, but you don't want to have a bunch of central "stores" of the latest version - then GitVersion allows unique versions by algorithms even if you have 100 branches under development.
While it is tempting to start with something simplistic - as you progress, you frequently end up building something like GitVersion - but just do it in hundreds of lines of CI code.
It's one of those "tradeoff" patterns like Kubernetes - infinite upscale means limits to how small and simple it can be - hence Hashicorp Nomad exists for a world simpler than Kubernetes.
@cbalane - FYI - I've started researching the topics relevant to this issue. I'm very much a beginner on our CI/CD feature set, so this is going to be quite a learning exercise for me.