-
Notifications
You must be signed in to change notification settings - Fork 28
Scripting API versioning #224
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
Should be also aligned with TS version also, see https://github.com/w3c/wot-scripting-api/blob/master/typescript/package.json#L3 |
Call 30/11/2020: need more use cases |
By the way, Nodejs has a runtime read-only version variable. |
In the same spirit we could have
In the Node.js case it is not well defined what kind of version string is used (e.g., Major.Minor.Patch) |
Call 2020-12-14 General question remains whether there is any need for version number. Use-cases are needed. |
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. |
Call 2021-01-18: Decided to wait before making a final decision (trying to gain more experience ) |
What I recommend doing:
|
Call 2022-02-20:
|
In order to solve this, we need to publish each version of the spec that has a version in the implementation. |
That should work for past versions where we have a clear published document. But let's consider the current phase:
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). |
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. |
Call 27/02/2023:
|
Call 22/01:
|
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
).The text was updated successfully, but these errors were encountered: