Version Scheme: Brain Storming

[tajmone]

EDIT — the SemVer scheme will refer only to the AsciiDoc sources!

---

We need to decide upon a version scheme for this project, to be associated with release tags on GitHub. The question is rather complex because an update in the project might be due to different reasons.

Here's some brain storming on the issue...

Technically speaking, there are various versions at stake in this repository:

• Book edition.
• AsciiDoc sources revision.
• Template(s) revision.
• Converted book(s) version, in various formats.

As for the Hugo Book edition, it refers to the last time the book contents where changed by its original author. I.e. that would be the First Edition.
The edition date might also be taken into consideration here, which in the PDF book is 2004, with the Word document being last edited in 2018-10-04 — although we might consider changing the date to that of the 1st release of this project, due to the small contents changes that were done with the author's supervision.

In any case, the book edition raises the general question of if and how further contents changes should be handled — although I think that this repository should aim at preserving the last edition by the original author, without further contents changes (these should be done in forks of this project, not here).

So, we could assume that the book edition is unlikely to change in the future, and treat First Edition as an immutable constant in the version scheme (regardless of whether the 2004 date will be preserved, or 2019 adopted).

The AsciiDoc sources revision is the primary focus of the version scheme, for it refers to source code files, and therefore well suited to adopt a scheme like SemVer 2.0.

Templates and pre-converted documents are more complex, for obvious reasons. For example, the HTML template might be updated to improve visual styles, leading to a quite different output document.

• Should this updated HTML document carry a different revision mark?

On the one hand, its contents are unaltered, but on the other hand its visual presentation might be drastically changed. End users focusing on obtaining always the latest document in a given format might wish that it bore some revision mark that allows distinguishing which one of two diffing documents is the latest release.

Since in the future this project might host a variety of output formats other than the current single-file HTML5 document, the issue of providing a good revision scheme should not be underestimated — for it might soon lead to confusion and version entanglement.

From a practical point of view, some third party projects might wish to point to specific tags of this repository to integrate its AsciiDoc source in their project (e.g. an IF documentation project, where the Hugo Book is just one of many AsciiDoc documents). In similar cases release tags are extremely important to allow targeting specific versions of the project (i.e. versions tested to be compatible with the importing project) by means of Git submodules inclusion, or even downloading specific files via cURL and exploiting raw.githubusercontent.com URIs that leverage tags instead of branches.

The same might be true for third party projects aiming to download specific versions of the pre-converted documents — although it's most likely that they'd be just targeting master branch, which always contains the latest release of all converted documents.

Clearly, version schemes like SemVer 2.0 can't pack all these different revisions information into a single semantic value. So the question is whether we should devise a custom scheme that can contain all these different version in a single string that would intuitively deliver clear information as to which version is the latest one, or whether we should focus only on the AsciiDoc source revisions.

It's important to note here that having release tags focusing only on ADoc sources would preclude tag-based checkouts and downloads to benefit from template updates in the importing projects — i.e. unless the whole project version moves forward whenever something changes in either one of the four independent elements (book version, ADoc sources, templates, converted docs).

This latter solution might introduce too many release tags, where projects targeting the ADoc sources would not benefit from most version bumps because updates to the various templates and pre-built documents are going to be more frequent than changes to the ADoc sources.

From these considerations, it's clear that the order in which the various elements at play were presented in the list at the beginning of this post do in fact reflect the natural order of changes propagation: any changes to the book edition (i.e. author contents) would affect the version of all other elements, whereas the reverse is not true (i.e. changes in a template will only affect its output document, without requiring a version bump in the element that precede it in the list).

Ultimately, it's a question of deciding whether the heart of this project are the AsciiDoc source file or the format-specific converted documents. I lean toward the ADoc sources, considering the pre-converted documents just an added bonus — the purpose of this project being the preservation of The Hugo Book in a format-agnostic format, where contents and styles are totally separated.

But, even if sticking to SemVer and the AsciiDoc sources only, we'd need to work out how to convey all these different revision aspects in the converted documents (as mentioned above) so that end users will always be able to tell which one of two documents is the most recent one.

References

• https://semver.org — Semantic Versioning 2.0.0.
• GitHub Help » Managing releases in a repository