DSI spec proposal: edition numbers with zero are "unlisted"

[castedo]

perm.pub and popgen.es treat edition numbers with zeros in a special way. Snapshot edition numbers with zero are not listed in the sequence of editions that are finer than a coast edition number without a zero. This extends to the empty edition number in that a base DSI does not result in a listing of snapshots with edition numbers than have a zero.

This functionality was added to be analogous to pre-releases in software packages. With software releases there are scenarios where an author wants to go though most of the steps of a release, but just short of making a full official release. Likewise with editions an unlisted 1.0.1 edition is just short of a fully listed 1.1. Additionally, editions like 0.1 etc... 0.2 ... do not get listed by default. This can serve a role analogous to beta releases. Still reference-able as a DSI, but treated as something less ready than an edition without a zero.

If this functionality of perm.pub and popgen.es is integrated into the baseprinterpress package then it could become a reference implementation for DSI and the criteria could be added for the presentation of DSI with zeros as "unlisted".

[xldrkp]

Hi @castedo! Could you please explain this in our next community call?

[castedo]

OK, I've marked my calendar to wake up early and attend. This particular discussion #4 is a bit narrow and focused, but I can also talk about the general idea behind how these numbered discussions in GitHub complement a living descriptive specification. I will add some more context to this GitHub Discussion for more background.

[castedo]

I should mention that this proposal is essentially already implemented in Hidos, perm.pub, and popgen.es.

This discussion is mostly thinking through what guidance to give in the specification regarding interoperability between software reading and writing document successions.

Here's some background info.

Multilevel edition numbers are edition numbers like 1.1, 1.3.2.1, etc... These are inspired by semantic versioning of software releases.

Documents are different that software, but traditional documents are also different than Baseprint document successions. My hunch is the same underlying fundamental reasons software developers find semantic versions useful will also apply to Baseprint document successions.

Working assumptions:

A) '0' is a confusing first edition number.
B) Most people will assume the first edition has edition number '1'.
C) Some authors, for some documents, will find multilevel edition numbering useful.
D) Multilevel edition numbers should be restricted to a simple data model of tuples of integers. They are not strings with special formatting.

Then it seems clear to me that:

E) The last integer in the tuple should never be zero.

This E) is a natural generalization of A) and it eliminates confusing '1.0' with '1', which are different tuples.

Another restriction COULD be:

F) None of the integers in the tuple can be zero. The tuples are of positive integers only.

However, there are two software practices that are suggestive of utility of having a special integer like zero.

1. Software developers often use some kind of marker or tag with a semantic version number to communicate a "prerelease", or a "beta", or a "release candidate".

2. Some software developer use 0.x releases to mean early stages that are of lower quality and for small audiences than 1.x releases.

So this proposal is to NOT adopt F) as a requirement and instead make edition numbers "unlisted" if any zero appears in the tuple. This means by default such an edition is not displayed and it is optional when and whether software shows "unlisted" editions. Some software might completely ignore unlisted editions, and in some contexts that might be what users want. Other software might show them in special views or with special non-default settings.

[castedo]

DSI spec is here: https://perm.pub/1wFGhvmv8XZfPx0O5Hya2e9AyXo/

[castedo]

Another approach for for this "unlisted editions" proposal is to document it in the spec as an experimental feature and upgrade Hidos to only support it when it is in experimental mode.

This would simplify the main part of the spec that does not include experimental stuff. The non-experimental criterion for an edition number becomes a nice simple "tuple of positive integers" and no complexity about zeros and unlisted-ness needs to be introduced.

[castedo]

Edition 2.3 has been updated https://perm.pub/1wFGhvmv8XZfPx0O5Hya2e9AyXo/2.3

Hidos issue created: https://gitlab.com/perm.pub/hidos/-/issues/8