mirror of
https://github.com/semver/semver.git
synced 2026-07-11 06:53:03 -05:00
[GH-ISSUE #459] SemVer Specification 1 #2068
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#2068
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @machitgarha on GitHub (Aug 19, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/459
First, I'm going to include it here:
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 commented on GitHub (Aug 19, 2018):
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 commented on GitHub (Aug 20, 2018):
@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 commented on GitHub (Aug 20, 2018):
@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 commented on GitHub (Aug 20, 2018):
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 commented on GitHub (Aug 20, 2018):
As you know, by varies from in. So, by the code not equals in the code.
From SemVer:
In the first specification, we read:
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 commented on GitHub (Aug 20, 2018):
@MAChitgarha, you seem to be trolling. Either issue a pull request or close this thread.
@machitgarha commented on GitHub (Aug 21, 2018):
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 commented on GitHub (Aug 22, 2018):
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 commented on GitHub (Aug 22, 2018):
@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 commented on GitHub (Aug 22, 2018):
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 commented on GitHub (Aug 23, 2018):
@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 commented on GitHub (Aug 23, 2018):
@MAChitgarha said:
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 commented on GitHub (Aug 23, 2018):
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 commented on GitHub (Aug 23, 2018):
@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 commented on GitHub (Aug 23, 2018):
@MAChitgarha, oh, I just edited it twice by the way. I usually don't encounter anyone online here this late at night.
@jwdonahue commented on GitHub (Aug 23, 2018):
@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 commented on GitHub (Aug 23, 2018):
@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 commented on GitHub (Aug 23, 2018):
@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 commented on GitHub (Aug 23, 2018):
@jwdonahue, OK, thank you!
@jwdonahue commented on GitHub (Oct 7, 2018):
@MAChitgarha, can you please close this issue at your earliest possible convenience? Thank you.