Epub-specs: define a logical semantic versioning for EPUB

[RachelComerford]

@llemeurfr: define a logical semantic versioning for EPUB. Usually in software development, a major version implies that backward compatibility is broken (EPUB 4 will be a good example), a minor version (digit 1) implies that backward compatibility is maintained but features are added, and a second digit is about error corrections (e.g. relaxing a type) with no additional feature (e.g. NO addition of elements). This as clearly not the case in the history of EPUB: is there a formal IDPF doc that defines this semantic versioning? If not, I suggest we create one and follow it in the future.

@mattgarrish: One thing to keep in mind is that there is no requirement that the package version match the specification number. Following on from what @llemeurfr wrote, a 3.1.1 that undoes the version change and restores/removes the features to make it compatible again with 3.0.1 would avoid the problem of 3.1 living on in its current state. It would be superseded by 3.1.1, and given that no one is using 3.1 now it would do so without version="3.1" getting any traction or 3.1 lingering on as another zombie.

@murata2makoto provided reference: https://www.w3.org/2001/tag/doc/versioning

[llemeurfr]

The "bible" of semantic versioning is Semantic Versioning (SemVer). It mainly addresses software versioning.

Versioning technical specifications is not as clearly defined; I only found the initiative of a company aimed at json schema versioning -> Introducing SchemaVer for semantic versioning of schemas, and no W3C document on the subject (note that W3C specs never use 3 digits versioning).

To come back to EPUB versioning, I would be in favor of defining:

• MAJOR = an change in the specification which breaks backward compatibility with the previous version.
• MINOR = a backward-compatible addition of functionalities.
• PATCH = backward-compatible bug fixes or modification of wording.

In the specific case of a backward-compatible evolution of EPUB 3.01, as functionalities are added (especially optional use of ARIA attributes), 3.02 does not fit well and 3.1 is already taken. This is not a patch from 3.1 neither, therefore 3.1.1 does not fit well.

Therefore 3.2 is my best bet.

For Japanese stakeholders who would prefer 3.0.2 because it shows that it is "closer" to 3.0.1 than 3.1, I believe that a clear explanation of the clean semantic versioning we want to adopt, along with explicit wording about the closeness btw 3.0.1 and 3.2, could satisfy them. @murata2makoto will certainly comment on this. Also, using 3.2 would solve @mattgarrish 's concerns about letting 3.1 in the void: 3.1 would then be superseded, period.

[mattgarrish]

Also, using 3.2 would solve @mattgarrish 's concerns about letting 3.1 in the void: 3.1 would then be superseded, period.

Yes, this is fine for me. I'm good with any approach that obviously and clearly supersedes 3.1 (i.e., has a higher number).

[murata2makoto]

I do not like 3.2 or 3.1.1 since they do not make clear that 3.1 is a mistake. That said, I would like to see "explicit wording about the closeness btw 3.0.1 and 3.2".

[llemeurfr]

It would be preferable to discuss the numbering of the upcoming version in #989 (I'll repeat my proposal there) and settle here on the semantic versioning we settle on for all future versions of EPUB.

[llemeurfr]

Re an "explicit wording about the closeness btw 3.0.1 and 3.2", just change "3.0.2" for "3.2" in the Google Doc and I guess you've got a proper wording.

My take here is that we shouldn't play with version numbers for political reasons (e.g. for making clear the EPUB 3.1 was a mistake).

[mattgarrish]

and settle here on the semantic versioning we settle on for all future versions of EPUB.

Do you mean _EPUB 3_ here?

If we want this to be true for all versions of EPUB, it also has to be brought to the publishing working group. The WG isn't bound to decisions made by the CG, even if we have a lot of overlap.

[mattgarrish]

Also, do we need to start a process document that we intend to follow within the CG, or what does resolving on this actually mean?

[llemeurfr]

I agree with both of you 1/ we need to start a process document for the CG 2/ we need to propose this to the WG for future EPUB 4 versioning.

[laudrain]

@llemeurfr As said in #984, this discussion is very theoritical. When revising 3.1, we were more practical, and this 3.0.2/3.2 discussion IMHO should stay within this realm.

[mattgarrish]

This would be a document for the CG to create and follow independent of the specifications themselves, so going to re-open this in publ-cg.