Semantic Versioning NOT being followed

[PeterDraex]

Contradicting documentation

Let's explore what the documentation says about this question:
Is the API of Restic 0.10.0 guaranteed to be compatible with the version version 0.9.6?

Documentation, page Home paragraph Compatibility says:

as long as we do not increment the major version, data can be read and restored

This suggests, that you are making a commitment NOT to make any breaking changes while only updating the MINOR version. The answer is YES.

However, just two sentences above documentation says:

restic follows Semantic Versioning to clearly define which versions are compatible

And the Semantic Versioning specification says:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time.

This suggests that API can change at any time. The answer is NO.

So what's right? Is the API stable or not?

Proposed solution

If API is currently considered stable, the version should be changed to 1.0.0 as soon as possible, to avoid any confusion.
Until then, this needs to be made clearer in the documentation, explicitly mentioning that API is stable from version 0.x and won't change in version 1.0.0.

[rawtaz]

No need to yell as if the world is ending ;-)

I agree the texts you found are contradicting. We'll look into it. Thanks for noticing this!

[PeterDraex]

Oh, sorry about that. Feel free to edit my post so it’d be more graceful. @rawtaz

[rawtaz]

No worries whatsoever, I understand you were just being clear 👍

[schmitch]

https://semver.org/#spec-item-4

[cdhowie]

Note that semver as it applies to restic is not about the internal restic API, but about the layout of the repository in storage. Restic's internal APIs may change at any time; there is no public API (aside from the command-line interface). So the primary question you've asked:

So what's right? Is the API stable or not?

Is actually totally irrelevant. This should be asking about the repository format and not the API.

[PeterDraex]

@cdhowie
Documentation states:

The repository and data structures contained therein are considered the “Public API”

So that's what I mean when I'm asking about stability of API (along with CLI commands).

[oscarbenedito]

Are there any updates on this? The compatibility page still states that restic is following semver (therefore being unstable), although the website suggests otherwise (even if it never explicitly asserts stability).

Is there any assurance of stability?

[rawtaz]

Since the software isn't versioned 1.0 yet, presumably you should in the end be prepared that things might change. That said, as you have seen the maintainers and developers do their utmost to keep backwards compatiblity and stability. It's not always doable, but in general I would say it's working quite well :)

[skrajewski]

I also recommend considering restic as a stable software and marking it according to the SemVer as 1.0.

When it comes to the API – stability concerns chiefly the public API, both the repository format and CLI interface. The latter in restic had breaking change in the version 0.10 because of #2546 (I personally faced it).

In my opinion, it should be replaced gradually, e.g., by introducing a feature flag first to turn on the new behavior. After some time, we'll finally replace it, but with the ability to use the old behavior by using some feature flag. I know, since the restic is not yet in 1.0, it doesn't have to follow this practice. However, it looks like restic is stable enough, and many people take advantage of it. That's why I think it's reasonable to treat them as stable software and avoid BC, at least in the scope of a single major version.

[rawtaz]

To those that are concerned about this, I have two questions:

• What actual and practical problem are you experiencing due to restic being versioned 0.10.0 instead of 1.0.0? Please note, actual practical problem.

• What text on the restic website would you like to change in order to make it, in your view, more reasonable that restic is versioned 0.x instead of 1.0, and how would you like the changes formulated?

[oscarbenedito]

For the first question: there isn't an actual practical problem, in the sense that the program will work equally whichever the tag. If the website said "this program might break any backups on any update", there wouldn't be any actual practical problem, but you can see why that would be a problem for a user. The problem is that the user is supposed to rely on a program the developer has made clear is not reliable. By having having a 0.x.y version you are saying (quote from https://semver.org/#spec-item-4): "Anything MAY change at any time. The public API SHOULD NOT be considered stable."

For the second question: The current text is:

Backward compatibility for backups is important so that our users are always able to restore saved data. Therefore restic follows Semantic Versioning to clearly define which versions are compatible. The repository and data structures contained therein are considered the “Public API” in the sense of Semantic Versioning.
We guarantee backward compatibility of all repositories within one major version; as long as we do not increment the major version, data can be read and restored. We strive to be fully backward compatible to all prior versions.

Which I think would be great if you had already released 1.0.0 (the second paragraph talks about changes made after 1.0.0), however, in this situation, it is very misleading. Indeed, if I didn't know about Semantic Versioning, I would think that until 1.0.0 is released (the next major version), no breaking changes will be applied. In reality, nearly none of the rules of SemVer have started to apply, because they only do after 1.0.0.

I understand that even in a 0.x.y version, there are efforts to not make breaking changes, so I would change the following: I would explicitly write that the second paragraph only applies after 1.0.0 and I would add another paragraph talking about the efforts made to not break anything during initial development. For example:

Backward compatibility for backups is important so that our users are always able to restore saved data. Therefore restic follows Semantic Versioning to clearly define which versions are compatible. The repository and data structures contained therein are considered the “Public API” in the sense of Semantic Versioning.
Once version 1.0.0 is released, we guarantee backward compatibility of all repositories within one major version; as long as we do not increment the major version, data can be read and restored. We strive to be fully backward compatible to all prior versions.
During initial development (versions prior to 1.0.0), maintainers and developers will do their utmost to keep backwards compatibility and stability, although there might be breaking changes without increasing the major version.

I hope this helps understand the point of view :)

[rawtaz]

@oscarbenedito Would you like to make a PR with those text changes (in the restic.net repository)? Otherwise I'll do it, either way is fine by me :)

[oscarbenedito]

Sure! I'll do that.

[rawtaz]

Closing as it's fixed with restic/restic.net#22, thanks @oscarbenedito!