Optional field(s) to specify used versioning schema

[grv87]

From developers and package managers point of view, it is important to know not just the version, but which versioning schema is used. Particularly, whether it is SemVer-compliant.

It would be good if this information was available in .ABOUT file together with version number.

Other examples of version schemas:

• CMSVer
• CalVer
• Romantic Versioning

There is even an attempt (intention?) to make something universal and self-describing: Version Schema.

[chinyeungli]

@grv87 Thanks for the ticket.
Would you mind providing a more details explanation of what do you mean? Perhaps a use case/example?

Do you mean to provide field to log which version of AboutCode Toolkit was used? or?

[grv87]

@chinyeungli, sorry for the delay. Took time to find a good example.

Do you know what SemVer is?

If not, brief overview.

When an author of software assigns a version to his product he can choose whatever version he wants.
There are usually some rules implied and imposed by tools, but, in generic case, version is arbitrary.
For example, in 289dc8c you updated ABOUT File Specification version from 3.1 to 3.1.2. Why this version? Not 4.0, 3.1.1 or 3.1_patch2?

A while ago some smart people figured out that everybody - developers, users, tools - could benefit from having some rules how version should be formatted and how it can be changed.
This way versioning schemas appeared.

The most known schema must be semantic versioning (SemVer).
If software follows SemVer then its version should contains three parts, MAJOR.MINOR.PATCH, and optional pre-release labels and build metadata.
There are some rules when each part should be incremented. Particularly, increase in major version means that there is a breaking change.
How this information can be used? If the user (consumer) has version 1.2.3 AND knows that the version complies to SemVer then he can make safe assumption that 1.2.4 and 1.3.0 should work too (without change in his own code), but 2.0.0 probably not.
But to make these assumptions he must be sure that it complies to SemVer.
If versions are arbitrary then these assumptions are invalid, and even 1.2.4 could be incompatible.

Unfortunately, everybody stores the version and nobody stores the versioning schema. So, all these assumptions I described above can be made only manually. The user should go to software website or documentation and look for, or ask developers what versioning schema used.
(The only known solution I know is already mentioned http://versionschema.org)
I was hoping that ABOUT specification would change that and introduce versioning schema as first-class field in software metadata.

Consider itself current version of ABOUT File Specification. It can be described with the following ABOUT:

about_resource: SPECIFICATION.rst
name: ABOUT File Specification
version: 3.1.2
copyright: Copyright (c) 2013-2017 nexB Inc.
...

As a user of this resource I would like to know whether its version complies to SemVer (then I can make assumptions described above) or not.
Or maybe other versioning schema is used, and it has similar (or in other way useful) rules.
Note that when value of version field doesn't comply to SemVer (e.g. 3.1) then I know it's not SemVer from the beginning. But 3.1.2 does comply.

When I look in the history I know that previous versions were not SemVer-compliant. So, I must conclude that current 3.1.2 is not too.
If ABOUT would have separate field for versioning schema then I could know that from the beginning and don't make guesses.

[grv87]

Prototype of proposed changes: 09c1d4a

[chinyeungli]

Thanks for the information and suggestion. I will look deeper on this.

[chinyeungli]

@grv87 Sorry for the delay. Your above explaination are very detailed and helpful.
Instead of having to create a new field called versioning_schema, I am thinking perhaps metioning the version of AboutCode follows the rules of SemVer in SPEC or README is enough? Or as a developer, you still prefer to have this extra field in the ABOUT file?

[mjherzog]

Since we have adopted SemVer, we should document that rather than adding a field. The versioning of AboutCode TK itself does not, of course, tell you the versioning schema that applies to any component or package described by an ABOUT file.