SemVer Specification 1

[machitgarha]

First, I'm going to include it here:

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.

1. Could an API be GUI? Is it mentioned here? If so, where?
   1.1. If we can declare a project's API to it's User Interface, then changes to the code without any impacts in GUI would be ignored from versioning, because it's out of API. It seems worse not to version a change. So, what?
   1.2. If a GUI is a true definition of an API, then I don't understand a precise and comprehensive GUI. A precise GUI? A comprehensive GUI? I have no idea!

Thanks!

[grv87]

On 1.1 - how is it different from changing private code of the class without any impact on call specifications of public methods? All these are covered by increment of patch field.

@jwdonahue, don't you think that the project would benefit from the policy to ask questions on SO, not in GitHub issues?

[jwdonahue]

@grv87, yes. I personally don't run the show here, but I'd prefer to answer questions in SO, and there are more people there to help out than there are here. I've been trying for almost a year to get the list of issues here down to something like an actionable set of proposed changes, while trying to convince folks to close their own threads when their questions seem to have been answered or their proposals are unlikely to be accepted.

That said, I don't mind answering questions, provided we can get them answered and closed quickly.

[jwdonahue]

@machitgarha, question 1 has come up in the past. See #90 and linked threads.

@mojombo was addressing a specific problem when he wrote the spec, that addressed versioning of API's and packages, not GUI's. Extend it into other areas as you see fit. Even if you do use the scheme to cover GUI's, you're going to have to think hard about what constitutes a breaking change? Is it any change the breaks GUI test automation perhaps? In any case, every published change would require a version bump of some kind. You can't have two packages with the same version string and different content.

Unless you have further questions, please close this issue at your earliest possible convenience.

[machitgarha]

Thank you @jwdonahue, I'll check that thread later.

@grv87! What about adding comments to the code? It doesn't have any impacts on the output, but it's a change, so you can't ignore it (e.g. by merging it to a future change). Missing comments (for future references or working as a team) is not an incorrect behaviour related to the defined API, which is GUI.

[machitgarha]

As you know, by varies from in. So, by the code not equals in the code.

From SemVer:

For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself.

In the first specification, we read:

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation.

I think in the specification the word in should be changed to by. Then, we can say "OK, GUI is an API". By the code has a larger definition than in the code. From my opinion, "GUI, in the code" is imperfect, but "GUI, by the code" is a good expression. Am I wrong?

[jwdonahue]

@machitgarha, you seem to be trolling. Either issue a pull request or close this thread.

[machitgarha]

I'm going to close this thread, but in my head, this question is still open. Either I can't say what I mean or you can't or don't want to accept. If I'm wrong, you don't tell where.
BTW, thank you all.

[klehelley]

I guess jwdonahue's reaction is due to the last two comments that precede his. Your first question, "Could an API be GUI?" is completely OK, though a little imprecise regarding the situation described in 1.1 (I am not sure whether I'd be on point or not if I tried to answer it).

However, your answer to grv87 makes it look like you haven't put much thought into his answer, or haven't understood it. (And your example of having a release that differs only from the previous one by comments is hardly a compelling one. Nobody does that; except in the context of Continuous Deployment -- in which case SemVer is probably a bad choice of versioning scheme.)

And the message following it makes no sense, in that it seems to be advocating that some content in version 1.0.0 of the specification should be changed to something that is already present in 2.0.0. I am not really sure why you are actually caring about version 1.0.0 of the specification, as far as I know it is not maintained (i.e. do not expect a version 1.0.1 or 1.0.0 anytime soon), and if changes are to be made they should refer to version 2.0.0 of the specification.

---

Regarding using SemVer for GUI, my 2 cents: it is extremely hard to define what a breaking change is in regard to the users. The good thing with API consumption is that either it works or it does not, no middle ground here. But with GUI one user may adapt to a modification with little effort, while another for the same change could end up completely lost and unable to continue without a lot of efforts. For that reason using SemVer as-is for GUIs is a lot of hassles. But it may work if you define precisely what kind of changes should result in which number being bumped. Ask yourself the question also of who will consume that version number and how it will help them, and whether SemVer is the right choice for them.

[machitgarha]

@klehelley, thanks for your comments!
Version 1.0.0 of the specification? No, I mean the first rule/spec of the Semantic Versioning Specification part, as I included it in my question.

Maybe I'm doing the wrong stuff, but why you should not have two versions that differ by comments? For example, if you forget to add comments when you code, you may want to add whole missing comments. We all know it's a common error. Consider we are using Git, shouldn't I commit that change? If I shouldn't do that, what should I do instead? Please help me in this case. Again, maybe I'm doing a wrong thing.

[jwdonahue]

It's a matter of what you're versioning. If you put a version number on a package, then if a single bit within that package changes, it must have a new version. Adding comments to code might not change the package content, in the unlikely case that your build tools produce the same outputs for a given input, in which case; there simply isn't a new version of the package. The whole point of semver is to provide enough information in the version string for folks to make informed decisions. If you cheat, they will likely notice eventually, and then they can't trust anything you publish, without resorting to full regression tests of every dependency they take on your product.

Consider that a comments in an interface file, are considered documentation relative that interface. It's probably not breaking, but it is a change and semver requires at least a patch increment.

@machitgarha, you should read all the threads at stackoverflow with a semver tag on them, and all the closed/open threads here, to learn something of the nuances of semantic versioning.

[machitgarha]

@jwdonahue, thank you very much. My problem on 1.1 has been solved. Say, for example, we can version new comments as a metadata change. Yes, "It's a matter of what you're versioning".

However, could you say why you don't accept this comment?

[jwdonahue]

@machitgarha said:

1.1. If we can declare a project's API to it's User Interface, then changes to the code without any impacts in GUI would be ignored from versioning, because it's out of API. It seems worse not to version a change. So, what?

Did the bits change in the package that delivered that GUI? If so, you have a new version and at least a patch increment. If no bits changed, there's no new version, assuming you have the non-existent repeatable build system. Most build systems claim determinism, but they include inputs that affect the output which are not part of the source code (dates, times, machine/user names, paths, log-file names, etc), so they cannot produce the same package from one build to the next, even if none of the compile-able code changed (ie, you only made comment changes). If the bits in the package are different, you have a new version.

Metadata is an adjunct to the version string. Changing just the metadata does not make the version string unique. SemVer compliant tooling sorts on X.Y.Z-prerelease.identifiers and nothing else. If you cut two versions that differ only in the metadata, users will get the first one they happen to find when they query your release feed(s). Do not change metadata without also modifying the fields that are used for precedence.

You would know all of this by now, if you had bothered to study my responses to similar questions here and at SO.

[jwdonahue]

I will add that truly deterministic build systems, always produce the same output no matter the machine, user, time, date or system configuration (did I miss anything?) at the time of the build. As far as I know, there's never been any such build system in the history of computing. Some projects have attempted it, but all of them that I am aware of have thus-far missed the mark.

Hence, every build should always produce a package with a new version tag on it.

[machitgarha]

@jwdonahue, thank you for your explanation.

Now I want to know why you didn't accept changing in the code to by the code, as I mentioned it here, and you said "you seem to be trolling"?

[jwdonahue]

@machitgarha, oh, I just edited it twice by the way. I usually don't encounter anyone online here this late at night.

[jwdonahue]

@machitgarha, you're wearing me down man. If you want to provide a pull-request for a specific change, please do so. I won't support that change because it just doesn't sit well with me. I think it's a nit at best.

[machitgarha]

@jwdonahue, that's simply because we live in two different countries! I don't see the black sky here!

And for your last comment, I don't want to harm anyone, especially someone who helped me (i.e. you!), but I really have these questions. I appreciate your patience in answering me!

[jwdonahue]

@machitgarha, please take your questions to stackoverflow. I am trying to reduce the noise level here so we can focus on actionable issues. User support is better handled on SO.

[machitgarha]

@jwdonahue, OK, thank you!

[jwdonahue]

@machitgarha, can you please close this issue at your earliest possible convenience? Thank you.