WIP: Concrete Versioning Proposal #1969
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
I think we should create a dedicated issue for it to keep better track of the problem, label it accordingly etc. Note: there are other task forces waiting for a common versioning proposal (see w3c/wot-scripting-api#488). |
|
I have organized the discussion and marked what are decided points between @lu-zero and @danielpeintner. There are still open points which are noted there as well. Everything that has been discussed, it is moved to an Archive section |
|
In order to automate changelogs conventional commits + something like git-journal might come handy, (@relu91 already mentioned it I think). |
|
TBC: CBOR-LD requires resources to be frozen. To be followed-up |
TallTed
suggested changes
Sep 30, 2024
|
|
||
| ## Versioning for 1.0 and 1.1 Specifications | ||
|
|
||
| - With each REC, we publish the following files: | ||
| - Ontology files in form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM | ||
| - Ontology files in the form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM |
There was a problem hiding this comment.
Suggested change
| - Ontology files in the form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM | |
| - Ontology files in the form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and, soon, TM |
|
|
||
| ## Versioning for 1.0 and 1.1 Specifications | ||
|
|
||
| - With each REC, we publish the following files: | ||
| - Ontology files in form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM | ||
| - Ontology files in the form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM | ||
| - JSON-LD Context file | ||
| - JSON Schemas for TD and TM | ||
| - DECISION: We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). |
There was a problem hiding this comment.
Suggested change
| - DECISION: We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). | |
| - DECISION: We do not publish different versions of these files until we see a need (e.g., a bug that also has breaking changes to current implementations). |
Comment on lines
+20
to
+21
| 1. Early adopters (implementers before REC publication), which include specification developers, editors, testers, other TFs etc. | ||
| 2. REC publication users. Naturally, all early adopters are in this category as well. |
There was a problem hiding this comment.
Suggested change
| 1. Early adopters (implementers before REC publication), which include specification developers, editors, testers, other TFs etc. | |
| 2. REC publication users. Naturally, all early adopters are in this category as well. | |
| * Early adopters (implementers before REC publication), which include specification developers, editors, testers, other Task Forces (TFs), etc. | |
| * REC publication users. Naturally, this category also includes all early adopters. |
Comment on lines
+22
to
+26
| - To both users, provide concrete guidelines and rules on how implementations should be made that take the versioning into account. The lack of this is the reason why we do not have versioned resources for 1.0 and 1.1 specifications. | ||
| - Prioritize stability for post-REC users | ||
| - Make sure that quick changes are well-communicated to early adopters in the form of a changelog or similar | ||
| - Publicly serve all versions of all resources all the time | ||
| - Any change to any resource should bump the version inside the resource as well as the way the resource is obtained (e.g. URL, package manager, etc.) |
There was a problem hiding this comment.
Suggested change
| - To both users, provide concrete guidelines and rules on how implementations should be made that take the versioning into account. The lack of this is the reason why we do not have versioned resources for 1.0 and 1.1 specifications. | |
| - Prioritize stability for post-REC users | |
| - Make sure that quick changes are well-communicated to early adopters in the form of a changelog or similar | |
| - Publicly serve all versions of all resources all the time | |
| - Any change to any resource should bump the version inside the resource as well as the way the resource is obtained (e.g. URL, package manager, etc.) | |
| - For both categories of user, provide concrete guidelines and rules for how implementations should be made to take versioning into account. The lack of such guidelines and rules is the reason we do not have versioned resources for 1.0 and 1.1 specifications. | |
| - Prioritize stability for post-REC users | |
| - Make sure that quick changes are well communicated to early adopters in the form of a changelog or similar | |
| - Publicly serve all versions of all resources, all the time | |
| - Any change to any resource should bump the version inside the resource as well as the way the resource is obtained (e.g., URL, package manager, etc.) |
|
|
||
| ### Summary of Basic Policy | ||
|
|
||
| - We assume that each resource belongs to a specification. If not, we can "invent" a virtual specification like wot that is hosting multiple resources and use that string to identify multiple resources. |
There was a problem hiding this comment.
Suggested change
| - We assume that each resource belongs to a specification. If not, we can "invent" a virtual specification like wot that is hosting multiple resources and use that string to identify multiple resources. | |
| - We assume that each resource belongs to a specification. If not, we can "invent" a virtual specification like WoT that is hosting multiple resources and use that string to identify multiple resources. |
|
|
||
| Notes: | ||
| - @mahdanoura : Also, the deprecation of terms needs to be considered, i.e. not removing but marking as deprecated. | ||
| - Best practices for RDF versioning should be studied. See https://www.w3.org/TR/prov-primer/ | ||
|
|
||
| #### Reflecting Meaning on Version Information | ||
| ### Reflecting Meaning of Version Information | ||
|
|
||
| How do we reflect a patch change on the artifacts? Do we use semantic versioning, use date, and ignore semantic versioning, do we use alpha, beta etc. |
There was a problem hiding this comment.
Suggested change
| How do we reflect a patch change on the artifacts? Do we use semantic versioning, use date, and ignore semantic versioning, do we use alpha, beta etc. | |
| How do we reflect a patch change on the artifacts? Do we use semantic versioning; use date and ignore semantic versioning; use alpha, beta, etc? |
|
|
||
| Notes: | ||
| - @mahdanoura : Also, the deprecation of terms needs to be considered, i.e. not removing but marking as deprecated. | ||
| - Best practices for RDF versioning should be studied. See https://www.w3.org/TR/prov-primer/ | ||
|
|
||
| #### Reflecting Meaning on Version Information | ||
| ### Reflecting Meaning of Version Information | ||
|
|
||
| How do we reflect a patch change on the artifacts? Do we use semantic versioning, use date, and ignore semantic versioning, do we use alpha, beta etc. | ||
|
|
||
| - ( @lu-zero ) A date afterward would be good "enough" for implementers. A release every month (in addition to semver) would also be good. We can also pipeline it and tag each resource exposed to github.io. | ||
| - ( @mjkoster ) Short commit hash would be fine. Monthly release may not make sense (unless there is a need) | ||
| - ( @mmccool ) To make things easy we should map our directories to the url structure. We should make all URLs are versioned | ||
| - @mahdanoura : According to OWL2 specification, for every ontology we can define an Ontology IRI (generic reference, should stay the same through versions) and a Ontology Version IRI. The difference is during dereferencing of the IRIs, the ontology IRI should redirect to the most recent version and the version IRI to the specific version. |
There was a problem hiding this comment.
Suggested change
| - @mahdanoura : According to OWL2 specification, for every ontology we can define an Ontology IRI (generic reference, should stay the same through versions) and a Ontology Version IRI. The difference is during dereferencing of the IRIs, the ontology IRI should redirect to the most recent version and the version IRI to the specific version. | |
| - @mahdanoura : According to OWL2 specification, for every ontology we can define an Ontology IRI (generic reference, should stay the same through versions) and an Ontology Version IRI. The difference is during dereferencing of the IRIs, the ontology IRI should redirect to the most recent version, and the versioned IRI to the specific version. |
Comment on lines
+196
to
+202
| - @egekorkan: we can do scoped versioning : td-version:resource-version -> 2.0.0.pre1+1.0.0.pre1 but this can be complicated. -> Not in favor of it anymore after talking | ||
| - others: Something like a changelog in the discovery can convey the meaning of change. Using one version would be simpler. | ||
| - @egekorkan: We cannot do semantic versioning in the usual sense since TD 2.0 has set the expectation already. Or we decouple the spec version from resource version, e.g. TD 2.0 can have resources in version 25.2.1 | ||
| - Cris: CSS simply increases the major version -> TD 2 has TD 2 resources. Until we get there, we can have TD 2.pre1 TD 2.a1. | ||
| - Luca: We can embed resource/format specific version inside the resource itself. | ||
| - Luca: We assume the TD 2.0 will not change but the resources can have big changes since they are moving targets. E.g. JSON Schema Draft 7 becomes obsolete and we decide to update to JSON Schema 2026-09 with totally new terms etc. In this case, JSON Schema resource gets a major version bump. | ||
| - In this case, the resource needs its own semantic versioning lifecycle but refer to which spec version it refers to. Example for JSON Schema version: 4.0.0+2.0 becomes 5.0.0+2.0 following the example above. Next TD version, we will get 4.0.0+2.0 -> 5.0.0+3.0 |
There was a problem hiding this comment.
Suggested change
| - @egekorkan: we can do scoped versioning : td-version:resource-version -> 2.0.0.pre1+1.0.0.pre1 but this can be complicated. -> Not in favor of it anymore after talking | |
| - others: Something like a changelog in the discovery can convey the meaning of change. Using one version would be simpler. | |
| - @egekorkan: We cannot do semantic versioning in the usual sense since TD 2.0 has set the expectation already. Or we decouple the spec version from resource version, e.g. TD 2.0 can have resources in version 25.2.1 | |
| - Cris: CSS simply increases the major version -> TD 2 has TD 2 resources. Until we get there, we can have TD 2.pre1 TD 2.a1. | |
| - Luca: We can embed resource/format specific version inside the resource itself. | |
| - Luca: We assume the TD 2.0 will not change but the resources can have big changes since they are moving targets. E.g. JSON Schema Draft 7 becomes obsolete and we decide to update to JSON Schema 2026-09 with totally new terms etc. In this case, JSON Schema resource gets a major version bump. | |
| - In this case, the resource needs its own semantic versioning lifecycle but refer to which spec version it refers to. Example for JSON Schema version: 4.0.0+2.0 becomes 5.0.0+2.0 following the example above. Next TD version, we will get 4.0.0+2.0 -> 5.0.0+3.0 | |
| - @egekorkan: we can do scoped versioning: `td-version:resource-version` -> `2.0.0.pre1+1.0.0.pre1`, but this can be complicated. -> Not in favor of it anymore after talking | |
| - others: Something like a changelog in the discovery can convey the meaning of change. Using one version would be simpler. | |
| - @egekorkan: We cannot do semantic versioning in the usual sense, since TD 2.0 has already set the expectation. Or we decouple the spec version from the resource version, e.g., TD 2.0 can have resources in version `25.2.1`. | |
| - Cris: CSS simply increases the major version -> TD 2 has TD 2 resources. Until we get there, we can have TD 2.pre1 TD 2.a1. | |
| - Luca: We can embed resource/format specific version inside the resource itself. | |
| - Luca: We assume the TD 2.0 will not change, but the resources can have big changes since they are moving targets, e.g., `JSON Schema Draft 7` becomes obsolete and we decide to update to `JSON Schema 2026-09` with totally new terms, etc. In this case, JSON Schema resource gets a major version bump. | |
| - In this case, the resource needs its own semantic versioning lifecycle but refer to which spec version it refers to. Example for JSON Schema version: `4.0.0+2.0` becomes `5.0.0+2.0` following the example above. Next TD version, we will get `4.0.0+2.0` -> `5.0.0+3.0`. |
Comment on lines
+205
to
+208
| - Scripting API's type definition versioning is currently based on JSON Schema version. Current thinking is to use `type-definition-1.2.0+json-schema-td-2.0.0+td-2.0.0` where everything is added after the + sign as informative text. | ||
| - There are cases like Scripting API HTML spec and the type definitions, TD Ontology in HTML and TTL. We need to decide if the versions of those are always the same. In the case of Scripting API, the spec can change but the type definitions don't (1) and vice versa (2). | ||
| 1. Informative text, explanation on the usage of a function in the TD spec (like not having `queryaction` in the spec but having it in the TD and JSON schema since 4 versions), WebIDL changes. | ||
| 2. Automatically, the type definition gets updated but the spec hasn't caught up. |
There was a problem hiding this comment.
Suggested change
| - Scripting API's type definition versioning is currently based on JSON Schema version. Current thinking is to use `type-definition-1.2.0+json-schema-td-2.0.0+td-2.0.0` where everything is added after the + sign as informative text. | |
| - There are cases like Scripting API HTML spec and the type definitions, TD Ontology in HTML and TTL. We need to decide if the versions of those are always the same. In the case of Scripting API, the spec can change but the type definitions don't (1) and vice versa (2). | |
| 1. Informative text, explanation on the usage of a function in the TD spec (like not having `queryaction` in the spec but having it in the TD and JSON schema since 4 versions), WebIDL changes. | |
| 2. Automatically, the type definition gets updated but the spec hasn't caught up. | |
| - Scripting API's type definition versioning is currently based on JSON Schema version. Current thinking is to use `type-definition-1.2.0+json-schema-td-2.0.0+td-2.0.0`, where everything is added after the `+` sign as informative text. | |
| - There are cases like Scripting API HTML spec and the type definitions, TD Ontology in HTML and TTL. We need to decide if the versions of those are always the same. In the case of Scripting API, the spec can change but the type definitions don't (1) and vice versa (2). | |
| 1. Informative text, explanation on the usage of a function in the TD spec (like not having `queryaction` in the spec but having it in the TD and JSON schema since 4 versions), WebIDL changes. | |
| 2. Automatically, the type definition gets updated but the spec hasn't caught up. |
Comment on lines
+224
to
+227
| Luca: It is also a tooling problem. The tooling can replace a version tag. A warning can be displayed if we don't bump the version. Changing the tooling, readme etc. doesn't generate the warning. | ||
| Luca: Artifacts from a release having different versions will confuse the users. Until a stable release, there is no meaning provided in semver anyways, you have to check the changes manually. | ||
| Ege: after the talk, I tend to agree that we should sync all resources all the time (pre-release and release) | ||
| ScAPI: Which Scripting API version uses which TD version and which version of Scripting API implementations (e.g. node-wot) use which version of Scripting API and TD. So this kind of (external) synchronization is also relevant. |
There was a problem hiding this comment.
Suggested change
| Luca: It is also a tooling problem. The tooling can replace a version tag. A warning can be displayed if we don't bump the version. Changing the tooling, readme etc. doesn't generate the warning. | |
| Luca: Artifacts from a release having different versions will confuse the users. Until a stable release, there is no meaning provided in semver anyways, you have to check the changes manually. | |
| Ege: after the talk, I tend to agree that we should sync all resources all the time (pre-release and release) | |
| ScAPI: Which Scripting API version uses which TD version and which version of Scripting API implementations (e.g. node-wot) use which version of Scripting API and TD. So this kind of (external) synchronization is also relevant. | |
| Luca: It is also a tooling problem. The tooling can replace a version tag. A warning can be displayed if we don't bump the version. Changing the tooling, readme, etc., doesn't generate the warning. | |
| Luca: Artifacts from a release having different versions will confuse the users. Until a stable release, there is no meaning provided in semver anyway; you have to check the changes manually. | |
| Ege: After the talk, I tend to agree that we should sync all resources all the time (pre-release and release) | |
| ScAPI: Which Scripting API version uses which TD version and which version of Scripting API implementations (e.g., `node-wot`) use which version of Scripting API and TD. So this kind of (external) synchronization is also relevant. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
@egekorkan , @lu-zero and @mahdanoura will work on it outside of the TF calls to come up with a concrete proposal based on the input provided by everyone. @relu91 will check asynchronously