Introduce straightforward, comprehensible version scheme

[TheAssassin]

#34 suggests to just release a 1.0. In a recent discussion with @probonopd, I proposed an alternative scheme which I think is very much superior to just starting with a 1.x release with the current state for multiple reasons. Before a decision is made, I think it makes sense to thoroughly discuss the semantics of such versioning.

Yes, I know, another lengthy issue... but there is no point in rushing things either...

In my opinion, the spec version number should be equivalent to the current AppImage type, and should be extended to a full major.minor.patch number. We could use semantic versioning, a concept widely used and well understood by programmers.

As a result, the current specification would be released as a 2.0.0, marking the initial release.

Keeping the numbers in sync makes it very straightforward for people seeking to implement support for a specific type to find the correct document. It makes it easier for us to ensure some sane versioning semantics on either end. And, after all, it is close to what we have done so far with the spec.

Main Semantics

The AppImage community can expect the following semantics:

• Every major breaking change leads to a new version of the specification, which also leads to a new type. As long as things can be kept compatible, i.e., only bug fixes and new compatible features may be added to the spec, as demanded by semver, which I think is a good strategy. Tools that work with AppImages can expect proper forward compatibility: any feature included in an AppImage type 3.2 can be expected from a type 3.9, too (i.e., >=3.2, <4). With a 4.0, they need to react and ensure their tool continues to work.
• Whenever a new major release is made, the old type will essentially no longer be maintained. While this may be confusing, in my opinion, this is a good idea. We are a small team and cannot support types to eternity. Situations leading to the creation of an entirely new type are really, really rare. And we want to bring this to people's attention then. Of course, good documentation of changes would be appreciated, including some "what changed?" or "what this means for me" snippets.
• Minor changes, e.g., the addition of a new runtime parameter, lead to minor releases. Tools that work with AppImages can expect reasonable backwards compatibility: if they support type 1 and type 2 up to 2.4 for instance, every AppImage that falls into that range is fully compatible. A newer AppImage of some hypothetical type 2.6, will continue to work, even though the newly added features cannot be easily used.
• Bug fixes should always supported, as permitted by semver. A tool that supports 2.6 AppImages should always accept any 2.6.x release, because the patch number only increases with bug fixes, after all.

Challenges

• Changes need to be evaluated correctly, including possible side effects. For instance, adding a new allowed compression type to the spec could be seen as a minor change at a first glance. However, it really is a major change. Tools that want to work with AppImages to, e.g., extract desktop integration information directly from the integrated filesystem need to know which ones to expect so they can implement support. Suddenly adding a new variant violates the semantics described above. Of course, once this happens, one can think of solutions to avoid such situations in the future. A very good idea is to just move those data into some .zip in between the runtime and the payload, as described in some other issue.
• Depending on the situation, it may make sense to continue maintaining some old type on a feature branch, e.g., when developing an entirely new type. But hey, after all, we take into account such minor inconveniences if it avoids complexity for users.
• Bug fixes can be backported at any time, but that means that we'll have to do release older versions of the specification in between. For instance, while the latest release is 2.7.1, we may have to make a 2.6.9 release. That, however, can be seen as an advantage, as it increases compatibility levels. That said, I do not expect such a situation. Once a 2.7.1 is released, all the tools should use that one from now on. I just wanted to mention this. (This is daily business in software release management anyway.)

I'm sure there are more. Please add yours in a comment.

[shoogle]

It might be worth starting a new numbered spec file for each major release and having a latest file that is a symlink to the most recent major release, plus a draft file where you add things that are not ready for the main files.

draft.md
latest.md -> appimagespec-v3.md
appimagespec-v3.md
appimagespec-v2.md

This way implementors can quickly see what the spec used to look like for a particular version without having to trawl through the Git history, plus it saves you having to write "New in version X" all over the place. The system could be extended to minor versions too, though that might be more trouble than it's worth.

draft.md
latest.md -> spec/3/appimagespec-v3.2.md
spec/3/appimagespec-v3.2.md
spec/3/appimagespec-v3.1.md
spec/3/appimagespec-v3.0.md
spec/2/appimagespec-v2.0.md

Caveat: now the Git history wouldn't show the difference between versions (since each version is in a new file) although the history of draft.md would essentially show this.

[probonopd]

As per discussion with TheAssassin, we will simplify things as follows:

• Instead of having multiple types (type 0, type 1, type 2) which were originally intented to be used like different profiles (as in PDF), we see that in reality only one type (the newest one) is actively used
• Hence, going forward, we will not have multiple AppImage types at the same time
• The types will hence be called versions from now on
• The AppImageSpec will try to follow semver with major and minor versions
• The AppImage runtime that implements a certain version of the AppImageSpec will have the same version number as the AppImageSpec, plus a patch level

[probonopd]

@shoogle have a look at https://github.com/AppImage/AppImageSpec/tree/next (still wip)

[TheAssassin]

Basically, this means whenever a new "type" (version) is released, all the tools will be switched to a new major version, same for the runtime. The old stuff will continue to work in theory, but we are going to cease support immediately since we are a small team anyway.

[probonopd]

Let's hope we won't end up like USB (in German but probably understandable even if you don't understand German) ;-)