Versioning of Registry Entries

[egekorkan]

As part of #378 at https://github.com/w3c/wot-binding-templates/blob/a052686548bec6aed802e7e309fabe5232c1556e/registry-requirements.md#entry-format under point 8, we have agreed to put a version field in the entry. However, we did not decide on how that version entry should look other than requiring a string. If we do semantic versioning, what does MAJOR, MINOR, PATCH mean. Relates a bit to w3c/wot-thing-description#1969

[egekorkan]

Call of 12 March:

• The dependencies of a binding can indicate versions as well
• Some directions:
  • Specify a versioning scheme: No strong opinions or proposals on this so far.
  • Let the submitters manage it but require some basics like unique versions
  • Latest version should be indicated and at least a chronological ordering would be good, i.e. not random hash values.
• We can wait and see how people are using the registry before deciding on a semantic versioning scheme. Until then, we can use a unique string/tag.
• The previous versions etc. can be in the summary document
• The date the entry is written, should be also in the document, thus a requirement.

[egekorkan]

Proposal:

• Each registry entry MUST have a unique version within its own versioning history. E.g., there can be a CoAP and an HTTP binding with the same version.
• All documents associated to the registry MUST follow the same versioning, i.e. all documents should update their version when there is a change.
• The version MUST be a string that is visible in all the documents.
• The version SHOULD contain a UTC-based date in ISO 8601 format in the form of YYYY-MM-DD.
• All the previous of the entry MUST be listed as links in the summary document.
• Each versioned entry MUST contain a changelog in the entry itself.

Some discussion points:

• Should there be time in the date?
• Should the date be mandatory in the version?
• Do we want a separate binding version and document version?

[relu91]

I think is sufficient to require an "ordering" function between the versions, whether this is done with dates or simple increasing integers it should not matter.