Semantic Versioning

[nedimAT]

Question

Hello,
have you heard about Semantic Versioning?
Would it be possible to implement Versioning like that? Currently we are using Renovate Bot to handle our dependencies, and usually allow them to auto merge bugfix releases. In my opinion your version number increments are random.

Kind regards, Nedim

PS: It would be nice to apply it to all structurizr projects (java, exporter and so on)

[bullshit]

And conventional commit based commit messages would be also great.

If you on the look for a release tool which supports semantic-versioning and conventional commit you could try

• nyx
• semantic-release with gradle-semantic-release-plugin

[simonbrowndotje]

have you heard about Semantic Versioning?

Yes. From my perspective it's a little more complicated/nuanced though:

• 95+% of everybody using the DSL parser are doing so via Structurizr Lite/on-premises/cloud and the CLI. So I'm primarily making releases for myself, and this 95+% of users probably doesn't even know what version numbers are being used.
• It is mostly, if not strictly, semvar (major has stayed at 1, minor changes when larger features are added).
• If we take the Java library ... there have been some breaking changes to the API, but the underlying workspace schema (the JSON) remains backwards compatible. Here's a question for you - the "Enterprise" concept has been deprecated, and ultimately the public API for dealing with this will be removed at some point soon. But it still needs to remain in the Java library for backwards compatibility. Should this increment the major or minor number? From an authoring perspective it's a major change, but it's still backwards compatible for serialisation and deserialisation purposes.
• I make very little income out of this tooling, so the simpler for me the better.

[nedimAT]

Just curious, is the 95% a real number (from some analysis tool) or a guess? And yeah, sure, from an end-user perspective it probably does not matter which version is in place.

But for everyone using the libraries (including you), it would make their lives easier to know if a change is backward compatible.

Back to your Java library example:
First, let us tackle the deprecation of some API or schema feature, if I have version 1.0.0 and only one commit adds some deprecation notes and warnings, then for me the following version is 1.0.1
If there is a second commit that adds some new API or schema feature (does not have to replace the deprecated one), then the version becomes 1.1.0.

If we remove a public-facing feature (API or schema), then this always bumps up the major version, so anyone using the code or schema can automatically see that version 1.0.0 will not be compatible with version 2.0.0.
So if we remove "Enterprise", whether in JSON or API, I think the version has to be 2.0.0.

As described in the Semantic Versioning 2.0.0 Specification:
MAJOR version if you make incompatible API changes
MINOR version if you add backward-compatible functionality
PATCH version if you make backwards compatible bug fixes

They also have a FAQ for such questions.

I also understand that this is open source and money is tight, but to me this just justifies using an already established way of dealing with common problems in our software engineering world rather than solving problems in a new custom way.

[simonbrowndotje]

Just curious, is the 95% a real number (from some analysis tool) or a guess?

It's a guess, and I'm sure the number is likely nearer 99% in all fairness ... there are 50K+ users on the cloud service, and the Docker images for Lite/on-premises/CLI have 100K+ pulls.

I do try to state in the changelog whether there are breaking changes, but I have limited time and the cloud service/Lite/on-premises installation is my priority. I'll try to do a better job with version numbers in the future though.

[nedimAT]

NIce, thank you!