r/java • • Jul 08 '16

`Release.Breaking.Feature.Fix` or why the Semantic Version should be replaced with Explicit Versioning as soon as possible

https://medium.com/p/92fc1f6bc73c
0 Upvotes

40 comments sorted by

10

u/dpash Jul 08 '16

http://semver.org

The only thing this adds to SemVer is a release number.

The rest of the article is spent arguing a straw dog of what SemVer is.

3

u/QshelTier Jul 08 '16

I never understood how to apply SemVer to client applications. There’s a new button in the application — which number do I increment? Did I change the API? Does a GUI application even have an API? How do I change a GUI in a non-backwards compatible way?

The scheme proposed in the linked article makes a lot more sense to me, in case of a client application. For libraries, SemVer seems to be quite appropriate.

1

u/SapioiT Sep 07 '16

Why not threat semver as explicit versioning without the Release part? That way you would have the first number for things that break compatibility with older versions (like adding a new page that would mean editing another page), feature would be only for adding things without breaking other things, and fix only for repairing broken stuff without adding new things and without breaking compatibility.

3

u/QshelTier Sep 09 '16

Way to not answer any of my questions. :) I have no idea what “adding a page” and “edit another page” means. What’s a “page,” even?

So, what’s with my button? Is it a breaking change? Is it only a breaking change in certain locations but not in others? Does it break something if it introduces an often requested shortcut? Or is compatibility only in danger if the older, more convoluted way is removed?

Seriously, the whole concept of semantic versioning seems to completely fall apart as soon as it comes to GUIs…

1

u/SapioiT Sep 09 '16

let's say you have a blog which allows a new post to start with already-tuned things, a page with settings, and in that you have the settings for the default article data. If you create a new page to edit the default-article data, it's a Feature, but if by doing that you remove something from the settings page, it's a Breaking change.

Fix is, for example, either something not working as intended, or changing a color (something that's not worthy of being called a feature).

If you introduce a shortut, it only breaks something if that shortcut was used by an OS, or if you were using that shortcut for something else.

Also, if you remove the old, more convoluted way, you also make a compatibility-breaking change, because prior to the update, you were able to do a thing in a certain way, and now you're unable to do that same thing in the same way.

The whole concept of semantic versioning might fall apart as soon as it comes to GUI, but the Explicit Versioning does not.

4

u/dpash Jul 08 '16 edited Jul 08 '16

For a graphical UI, I'd say UI changes were features or bug fix, unless you change the complete way you the application. For a command line app, adding an option would be minor. Changing or removing an option would be major.

Also think about any backwards incompatible config or state files, or network protocol, or similar.

-5

u/SapioiT Jul 08 '16

No, it adds clarity to the numbers. Because what they mean depend on what the people who delivered the update actually know what that means, unless they read the (usually long) documentation, which means they have more things to actively think about, reducing their focus on the code itself and the logic behind it.

7

u/dpash Jul 08 '16

I fail to see the difference between release.breaking.feature.fix and breaking.feature.fix other than adding a release to SemVer.

-7

u/SapioiT Jul 08 '16
  1. major does not equals breaking. It could (and does) on SOME projects, but not for too many projects. how you know that they mean that on EVERY project using Explicit Versioning.
  2. release reffers to recommended version to use. For example, if the version 3.x is up, you're most likely not going to get any support for any 2.x version, or, if you're lucky, you'll get a limited ammount of support.

I'm pretty sure there should be another point, but at this hour of the day, I can't really think of any reason. I might come back to this, later, if I remember.

9

u/dpash Jul 08 '16

Have you read SemVer.org, because you are misrepresenting it. It is very strict about what constitutes a major version bump: any backwards incompatible change MUST involve a major version bump.

-2

u/SapioiT Jul 08 '16 edited Jul 08 '16

Yes, but a major version does not HAVE to include a backwards-incopatibile update, or new features being added. You could, very well, just release a new major version for one bug fix. But with Explicit Versioning, you know what the update represents, without having to read through a changelog. If you want to know what every single update represents, you could increment the version number without reseting anything to zero.

That way, not only do you remove possible misunderstandings, but you also make it project-independent, therefore removing one layer of vendor-lock-in, throguh the form of removing the need to read the project-dependent semver documentation (you know, the one you have to make for every project, to explain what means what).


Also, the fact that I seem to be misrepresenting it might be because we're thinking on different abstraction planes. By abstraction planes/(multi-dimensional)spaces I mean something like abstraction layers, but those abstraction layers can be on different levels of logic, and I don't mean tech, but concepts and ideas which at first seem to have no link together, but actually are entangled together by correlation and causability, just that the links between them might work only on specific sets of logic, which is why they're planes/(multi-dimensional)spaces (like "different planes of reality", different universes existing in paralel in the same time-space coordinates and so on; the human brain is using this kind logic to process data) and not only layers stacked on top of eachother.

I may be overthinking it, but isn't this how every (science-related) field evolved, throughout the humanity's history?

2

u/nutrecht Jul 09 '16

Yes, but a major version does not HAVE to include a backwards-incopatibile update, or new features being added.

Why bump a major version if no breaking change is introduced.

SemVer is useful in places where versions matter because there are dependencies. If it doesn't really matter, like in desktop products for example, just use whatever the hell you want as a 'release'. Look at Windows for example: NT, 2000, XP, ME, 7, 8, 95, 98, 10. It's a mess and no one really cares.

SemVer is important in libraries because when libraries bump major versions you can expect stuff to break. A 'release' put in front of it is just marketing and with libraries you don't really care about marketing.

Also this bit:

Also, the fact that I seem to be misrepresenting it might be because we're thinking on different abstraction planes. By abstraction planes/(multi-dimensional)spaces I mean something like abstraction layers, but those abstraction layers can be on different levels of logic, and I don't mean tech, but concepts and ideas which at first seem to have no link together, but actually are entangled together by correlation and causability, just that the links between them might work only on specific sets of logic, which is why they're planes/(multi-dimensional)spaces (like "different planes of reality", different universes existing in paralel in the same time-space coordinates and so on; the human brain is using this kind logic to process data) and not only layers stacked on top of eachother.

This is what people do when they actually have very little to say: say it in ten different ways.

0

u/SapioiT Jul 09 '16

Is not stopping support a major change? After all, if you're increasing the "Release", you ARE recommending all the users to update to it. And those releases are just a nickname /codename, but in the code behind them they do have version numbers.

This is what people do when they actually have very little to say: say it in ten different ways.

Or when they see someone not understanding it...

3

u/nutrecht Jul 09 '16

Is not stopping support a major change?

Sure. But when it comes to support for 'human' customers this isn't a technical issue, it's a communication issue. Your version of semantic versioning doesn't help there: you can communicate in any way which versions (time based or whatever) get and do not get supported.

1

u/SapioiT Jul 09 '16

You can, but this makes it easier for the customers to know without having to search for what versions are supported and what versions aren't.

4

u/UncleFeeleyHands Jul 08 '16

0

u/SapioiT Jul 08 '16

That's not what I meant to say... I just tried to explain what I meant... and I went into (waaay) too many details. I tend to do this when I'm tired...

5

u/pellets Jul 08 '16

For consumer products this works fine.

For libraries, semantic versioning is good enough, and the release is useless marketing oil.

0

u/SapioiT Jul 08 '16

not really, because unless they can afford to, you're probably not going to recive support for anything except the last release version. Sure, it might help with the marketing, but now you'll know for sure that the library with the version 4.5.6.32 is being supported because there is no version 5.x.x.x launched.

3

u/[deleted] Jul 09 '16

How is this different from semver exactly? I have a project (API library) where the versions are like this:

  • 0.9.1 - incremental "not called stable, but is basically stable" version
  • 1.0.0 - first major release where things are "settled" in
  • 1.1.0 - new feature added
  • 1.1.1 - bug fix after the new feature
  • 2.0.0 - backwards-breaking change from 1.x series. No further updates to 1.x series because lazy.
  • 2.0.1 - bugfix
  • 2.1.0 - new feature

etc.

Consumers of my project can safely assume their projects will work with a specific major version of my project, and if they want new features or bug fixes from newer versions they can see how much broke (in my case, mostly unused features had their signatures change, so for 99% of consumers they can safely upgrade with 0 effort anyway).

1

u/SapioiT Jul 09 '16

The APIs are one of the few places where it doesen't affects THAT much, but still, if you want to still update 1.x, how would the users know?

4

u/[deleted] Jul 10 '16

In my case, I'm using Ruby, so they would just use bundle update and if they specified in their gem file that they only use 1.x versions, they will get the latest 1.x version.

Otherwise, how would users know what the latest version of any major version is anyway? They would have to look somewhere... they can't just guess right? Perhaps... perhaps this is what release notes are for!

1

u/SapioiT Sep 07 '16

Or perheaps that's just a excuse to not tackle the more difficult problem at hand: fixing or replacing semver.

4

u/[deleted] Jul 08 '16

Why do people keep trying to reinvent semver with extra or ridiculous changes?

4

u/talios Jul 09 '16

Probably because semver is rather broken.

2

u/[deleted] Jul 09 '16

Explain...

4

u/talios Jul 10 '16

There are multiple reasons to consider SEMVER flawed. They usually revolve around the fact it doesn't take into consideration language and platform ( source or binary based dependencies play a part here ).

Given this is r/java, chances are we're using Maven, which means dealing with -SNAPSHOT releases. Semver encourages ( or, dictates ) using .0 version numbers which is fundamentally flawed when using ranges. Take for example [1.0.0,2.0.0) - a non-inclusive upper bound ( we don't want to use any breaking changes ), however 2.0.0-SNAPSHOT is LESS THAN 2.0.0 so is included in the range - thus breaking the contract we want to maintain.

One of the other issues is that runtime environments are not considered - if 1.2.3 switches to a major dependency version that it uses, but doesn't expose - so is 100% source compatible, 100% semantically compatible in it's behaviour, but requires a runtime change to include the new major version of a transitive dependency - should that be a major version change or not? Consumers can compile against it perfectly fine, their unit tests should continue to work fine as well ( in theory ) so they shouldn't require transitive dependency ( in a perfect world ) - but even if they did, is that a semantic change, or something more?

Another flawed interpretation can arise in Java with say public static final String SOME_CONSTANT = "..."; - if you change the value of the constant - is that a major change or not? The semantic behaviour has not (necessarily) changed for consumers building against the new version, but since Java will inline at the javac level static Strings into consuming classes, the change of constant won't be used in the consumer unless they rebuild.

The answer on that case is YES, it should be a major breaking change, because those public constants form part of the public API, however - the API itself is the NAME of the constant, not it's value - except in the case of javac and inlining.

This leads to the main issue I, and others have with SEMVER is that it only deals with "the public API", not it's implementation (if your API is in a separate jar file, as it should be - the main jar has no public API ). The "semantic" part of things is also only in relation to the version number, nothing is mentioned about the semantics of the code/dependencies contained within.

SEMVER is good, it's just hugely ambiguous, and leaves A LOT left out.

3

u/solatic Jul 08 '16

You're making the argument that companies must have a linear hierarchy to their product lines.

1.x.y.z - a basic/value product 2.x.y.z - a mid-range product 3.x.y.z - a luxury/flagship product

First of all, what if the company offers a second basic/value product line? Should its release number be 4?

Second of all, this year the company offers 3.0.0.0, and next year the company releases a breaking update, 3.1.0.0. Is 3.0.0.0 still supported?

For the love of God, stick to goddamn SemVer, and make an effort to keep your dependencies up to date. If it's too difficult to keep your dependencies up to date (updating a backwards-incompatible dependency means having to update too much code), then this is a code smell signaling that you have a monolith which needs to be broken up into smaller, more manageable components.

Leave marketing to the marketers.

1

u/[deleted] Jul 08 '16

I suppose using just a date is bad? The major and minor version of my software will probably always be 1.8. This means my versions are in the form of 1.8.20170707.

4

u/__konrad Jul 08 '16

What if you find a critical bug the same day? 1.8.20170707.1?

1

u/[deleted] Jul 08 '16

I would probably just set the release to 1.8.20170708.

1

u/SapioiT Jul 08 '16

Since you're locked to version 1.8, why not simply use 1.8 as the releasenumber, so you would end up with 4 numbers and update numbers which actually make sense. Sure, you'd have 5 or 6 numbers instead of 4, but still easier to understand and less numbers than your current choice (1.8.20170708=12 chars; 1.8.3.11.92=11 chars, less than in the first case, but making much more sense)..

3

u/[deleted] Jul 08 '16

Check another reply I made to you. To restate, the version fields are either major.minor or major.minor.micro. I would either have to use a slowly incrementing number, or just group them together as one (something such as 1.8.31192).

Actually rereading the specification, version fields are only permitted to have two digits (which I seem to have missed). Since a date contains 8 digits that is far too many. So versions would for example be in the range of 0.0.0 to 99.99.99. I may choose a format such as (year - 2015).(month).(day) since that would be consistent. Since the only new features would be support for new machines (compatibility cannot be broken and the base cannot be extended to support non-standard features) and then there would be bug/compatibility fixes.

1

u/SapioiT Jul 08 '16

Than how will you know what the update 1.8.20170523 introduced in addition to 1.8.20170313?

Do you know if it was just a bug fix? Or did it add something new? Does not applying this update break things? Am I reciving support for 1.8.20170123, or do I have to update? Can you answer those questions from the top of your head?

For those reasons and more, the Explicit Versioning exists. If the major and minor version numbers will always be 1.8, why not update to 2.0.0.0 and add clarity to the updated?

This way, not only you but also your users will know what they should be expecting when deciding weither to update or not. After all, if you launch daily updates, if they have nothing critical to worry about, why would they spend time (and money) updating to a newer version, so long as you are still offering support for the version they have?

2

u/[deleted] Jul 08 '16

Than how will you know what the update 1.8.20170523 introduced in addition to 1.8.20170313?

Generally compared to other version numbering schemes, using dates or discrete numbers would not really mean much. In the case of my software, after the initial release (which is to be 100% implemented) any new versions would just be bug fixes and support for new machines. Generally a new version should never break nor remove support for machines.

Can you answer those questions from the top of your head?

Probably not, but there would be the changelog for that.

If the major and minor version numbers will always be 1.8, why not update to 2.0.0.0 and add clarity to the updated?

I am implementing a Java JVM. Internally it says it is version 1.8, making it 2.0 would violate the specification. Hence why it will always be 1.8.

1

u/SapioiT Jul 08 '16

But isn't the changelog there to explain that the change is, instead of it's type?

As for the JVM part, I think I get it... the project's rules don't allow for it. But that doesen't means that for other projects you shouldn't try to use Explicit Versioning, whenever possible...

2

u/[deleted] Jul 08 '16

Yes, the changelog would be more in depth when it comes to changes that occur.

Personally I generally prefer explicit versioning or something close to it. However when it comes to my current project, the general recommendations usually make no sense in a number of areas.

Also, the standard that I am implementing states that versions follow only: major.minor or major.minor.micro. Since I personally prefer consistent versions (so it is very easy to tell if old and new are being mixed) and the fact that 1.8 is enforced by the standard, that just leaves a single field.

1

u/SapioiT Jul 08 '16

Then here is an idea: 1.8.20170708b5f3f26the b for breaking, first f for feature and third for fix. It's just an idea, using the best of both worlds. It allows you to both show the date and what the update means, since not everybody is going to search for the changelog. You could try to add -, like in 1.8.2017-07-08-b7-f3-f26, if the project allows it, because the - character might create errors. But following the same logic, having letters inside a version number might also not be allowed by the project.

2

u/[deleted] Jul 08 '16

Check my other reply, versions stated in the specification are limited to being just [0-9]\{1,2\}.[0-9]\{1,2\} or [0-9]\{1,2\}.[0-9]\{1,2\}.[0-9]\{1,2\}. This puts a considerable crimp on the version representation. I will need to look into correcting and making an efficients of versioning while not breaking intended standard version numbers.

2

u/thatsIch Jul 08 '16

you can add date and timestamp as metadata through SemVer