Scripting API versioning

[relu91]

In the last two calls, we decided to define proper versioning for the API. My suggestion is to publish the FULL WebIDL as a standalone document and use it for versioning. For example, the URL https://w3c.github.io/wot-scripting-api/1.0/web_id identifies the specs of the API version 1.0 (we can choose a different URL schema as well). This may help also to sync the documentation with the actual API version ( This "fake" URL is referring to the same API spec but from older documentation which it was later updated for minor editorial issues: https://w3c.github.io/WD-wot-scripting-api-20181129/1.0/web_id )

We should also specify a runtime property that developers can call to know to which WebIDL version the API implementation is referring to. It could be a rather simple property under the WoT namespace (i.e. WoT.version).

[danielpeintner]

Should be also aligned with TS version also, see https://github.com/w3c/wot-scripting-api/blob/master/typescript/package.json#L3

[danielpeintner]

Call 30/11/2020: need more use cases

[relu91]

By the way, Nodejs has a runtime read-only version variable.

[danielpeintner]

In the same spirit we could have

• api.version
• td.version // I am not sure whether the td version is actually required given that the api version points to a TD version already implicitly

In the Node.js case it is not well defined what kind of version string is used (e.g., Major.Minor.Patch)

[danielpeintner]

Call 2020-12-14
@relu91 suggests to use version in WoT namespace
@zolkis notes that APIs should no longer break API. Programming by version is no longer recommended. Instead extend new API.

General question remains whether there is any need for version number. Use-cases are needed.
@ashimura mentions TD related issue w3c/wot-thing-description#932

[relu91]

I've been thinking about use cases for a runtime version variable. As we discussed in previous calls the main usage of such a feature is to adapt script behavior to different API versions. So to put it simply:

if(WoT.version === "1.0"){
   // read a property without calling the value function
} else {
   // read a property calling the value function
}

As @zolkis suggested we should encourage feature detection techniques instead of relying on this version variable ( which in general I consider a bad coding pattern too). Taking the code it could be rewritten like following:

if(!isValueSupported()){
   // read a property without calling the value function
} else {
   // read a property calling the value function
}

function isValueSupported() {
   // expose a temporary fake Thing called test
   // ....

   let result = test.readProperty()
   
   // destroy fake Thing
   return result.value !== undefined
}

On the other hand, there might be possible runtime behaviors that are really difficult to detect. Currently, I tried to find a concrete example but I cannot find any. I speculate that some function side effects which influence system behavior require the simulation of real thing-to-thing interaction. The experience from other major JS libraries/runtimes indicates that feature detection is not always enough; for instance Node, Vue, Angular, React has a runtime version variable. At the same time, it seems that other Web API does not use the version parameter.

My opinion is that we should wait until we gain more experience from runtime users and implementers. Meanwhile, we should encourage feature detection techniques as much as possible. let's talk about this in today's call.

[danielpeintner]

Call 2021-01-18: Decided to wait before making a final decision (trying to gain more experience )

[zolkis]

What I recommend doing:

• node-wot links to TR versions of the spec that it's implementing.
• the tip of the spec repo (draft) can be linked from the dev branch of node-wot (main).

[relu91]

Call 2022-02-20:

• Reviewing this issue after a while.
• @relu91: from node-wot POV, it is hard to refer to the right document format
• We don't have the right way to proper link types with the document version.
• @zolkis: we already have the mechanisms to handle it, so it's a delivery problem
• @danielpeintner: node-wot has version branches with fixed types.

[zolkis]

In order to solve this, we need to publish each version of the spec that has a version in the implementation.

[relu91]

node-wot links to TR versions of the spec that it's implementing

That should work for past versions where we have a clear published document. But let's consider the current phase:

• Last published Scripting API document: https://www.w3.org/TR/2020/NOTE-wot-scripting-api-20201124/ (way too old)
• Node-wot implementing a hybrid future set (mostly lacking behind) of what is stated in our latest editor draft
• Typescript types in sync with the current document structure.

What we need is the ability to ship node-wot with the right document version connected. This also includes experimental versions of node-wot (like the current ones 0.8.x). Probably we just need to commit to publishing more often so that we have the correct snapshots. One rule of thumb could be to publish every algorithm fix or breaking change (editorial changes can be bundled together or marked as not substantial).

[zolkis]

Right, we should have a tracking label for PRs that induce changes affecting the implementation.

We don't necessarily need to do it by W3C publication. We can also link to a specific version/tag of the index.html file in github.

[relu91]

Call 27/02/2023:

• @relu91 tags are good
• @zolkis we need a tag policy
• @danielpeintner publishing more often is not practically possible (not on a weekly basis at least)

[relu91]

Call 22/01:

• Group ok for closing