align teidata.version with Semantic Versioning Specification, closes #1993

[peterstadler]

This PR updates the regex used for defining the value of teidata.version to match the Semantic Versioning Specification. In fact, it's a slight modification of the provided regex at https://semver.org to work around the special flavor of XML Schema Regular Expressions (see https://www.regular-expressions.info/xml.html).

Additionally, the english prose was updated and some 'wrong' @version attributes removed from the Guidelines source.

[sydb]

See individual comments.

[sydb]

I really don’t want to say we follow this spec. It is far too restrictive for our use, I think.

• Our semantics for MAJOR, MINOR, and PATCH are different than theirs
• We want build metadata considered when determining precedence
• SemVer is about the API; we are about schemas and documentation

Thus I would much prefer we either not mention the Semantic Version Specification, or (better, IMHO) mention it as the inspiration for the system we use, and cite it properly in the BIB. Something lie “using the syntax of the Semantic Versioning system” or “based on the Semantic Versioning system”, with a link to the BIB (which gives a pointer to the 2.0.0 spec).

[sydb]

I have not hand-parsed the regular expression and seen that it makes sense. I did test it against all 71 test cases, and it correctly flags the first 31 as valid and the remaining 40 as invalid. So this looks like the correct W3C regular expression for SemVer.
So hurrah! to @peterstadler for a job well done. I think he should submit this to the SemVer folks, but hope he’ll coordinate with me, as I may have an entirely different regexp for them, as well.
That said, I think we should be much more restrictive for @version of <TEI> and <teiCorpus>. Something more akin to 4\.1(\.(0|[1-9]\d*))?(-(alpha|beta))?(\+([\-0-9a-zA-Z]+(\.[\-0-9a-zA-Z]+)*))?.

[sydb]

1. “consists at least of three parts” should probably be “consists of at least three parts”.
2. But in truth (as alluded to above), I am not sure why a user should be required to specify the patch number in the @version of <TEI> or <teiCorpus>.

[duncdrum]

I have to say the question if TEI (guidelines and stylesheets) is an api according sem-ver definition is not straight forward to me. Actually i m leaning more towards saying yes.

IIRC anything that is build metadata should be sorted alphabetically when determining version precedence, no?

[sydb]

Maybe it’s me … I am certainly an old dog in a new trick game. But I cannot see TEI as an API. (In fact, I just yesterday got a virtual earful of how it is problematic that there is no Web API that allows one to get snippets of the source of the Guidelines.) An API “defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.” [Wikipedia]. What call or request can a software system make to TEI?

As for build metadata, I wish that were so, @duncdrum, but what the SemVer spec says is “Build metadata does not figure into precedence”.

But I think we want build metadata included in our little universe, although we may want to go ahead with this ticket first, and then add it later.

[raffazizzi]

VF2F subgroup thinks that it is appropriate to say that a TEI version number follows the Semantic Versioning Specification.
Before we merge, however, could @peterstadler address @sydb's other comments?

[sydb]

Council SVF2F NA group thinks:

• Still pending @peterstadler to make mods requested by me (per @raffazizzi)
• Still need to decide whether or not the value of @version should be required to match the (beginning of) the version of the schema
• Still need prose to explain what it means to be conforming to SemVer

[sydb]

Council SVF2F NA group still thinks the 3 items listed on 07 May should be addressed. For 2nd bullet point we suggest that there be a soft requirement. I.e., prose that says “they should match”, not an actual schema test that will fail if they don’t.
@peterstadler should consider himself poked about the other two bullet points.

[ebeshero]

Council meeting 2022-04-08: Add language to indicate that for the TEI Guidelines we’re inspired by the semantic versioning conventions but we’re applying our own TEI conventions to it (not following the custom for identifying “major” / “minor”.)

[sydb]

Note: commit 7131846 did nothing except merge in the 664 commits that had been made to 'dev' branch in the interim.

[sabineseifert]

Council at VF2F 16 March 2024:

Discussion

• Main problem: versioning system (major-dot-minor-dot-patch followed by optional ‘a’ or ‘b’, or supposedly ‘α’, ‘Β’, “alpha”, or “beta”) is not permitted by the datatype used for TEI/@version and teiCorpus/@version
• datatypes for other version numbers need rationalization as well
• teidata.version should allow for multiple variations
• Should the TEI provide a datatype that is not used by any actual element or attribute defined by the Guidelines themselves?

Council decision: Development of a comprehensive system for datatypes of version numbers

• An uber-datatype (e.g. teidata.version or teidata.versionIndicator or teidata.versionNumber) should be defined as an alternation of various specific datatypes which match particular kinds of version numbering systems. E.g.:
  • teidata.semVer would match the major-dot-minor-dot-patch-optional-dash-details kinda thing (TEI/@version, teiCorpus/@version)
  • teidata.calVer would match date-like version numbers (e.g.: 20240315)
  • teidata.unicodeVer would match theirs (att.gaijiProp)
  • teidata.version.versionNumber (e.g. 4.7.0)
• teidata.version would be defined as something like

<dataSpec ident="teidata.version">
<content>
<alternate minOccurs="1" maxOccurs="1">
        	 <dataRef key="teidata.version.semVer"/>
        	 <!-- follows semantic versioning syntax, see https://semver.org/ -->
        	 <dataRef key="teidata.version.calVer"/>
        	 <!-- follows calendar versioning syntax, see https://calver.org/ -->
        	 <dataRef key="teidata.version.unicodeVer"/>
        	 <!-- an enumerated list of Unicode versions (currently in att.gaijiProp)-->
        	 <dataRef key="teidata.version.versionNumber"/>
        	 <!-- for backwards comopatability -->
    	 	</alternate>
	 </content>
</dataSpec>

• original issue #1993: value of @version on TEI/teiCorpus will be changed to teidata.version.semVer
• SB: a TEI schema should permit only 1 possible value on TEI/@version or teiCorpus/@version, namely that schema’s version number. That schema number might be derived by appending the schemaSpec/@ident to the version number of the schema pointed to by @source. [This would be a new ticket.]