Skip to content

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

Closed
relu91 opened this issue Jul 27, 2020 · 14 comments
Closed

Scripting API versioning #224

relu91 opened this issue Jul 27, 2020 · 14 comments
Labels
propose closing Solutions exists and labelled as to be closed soon

Comments

@relu91
Copy link
Member

relu91 commented Jul 27, 2020

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
Copy link
Contributor

@danielpeintner
Copy link
Contributor

Call 30/11/2020: need more use cases

@relu91
Copy link
Member Author

relu91 commented Nov 30, 2020

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

@danielpeintner
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member Author

relu91 commented Jan 18, 2021

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
Copy link
Contributor

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

@zolkis
Copy link
Contributor

zolkis commented Feb 20, 2023

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
Copy link
Member Author

relu91 commented Feb 20, 2023

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
Copy link
Contributor

zolkis commented Feb 20, 2023

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

@relu91
Copy link
Member Author

relu91 commented Feb 20, 2023

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:

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
Copy link
Contributor

zolkis commented Feb 20, 2023

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
Copy link
Member Author

relu91 commented Feb 27, 2023

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 relu91 added the propose closing Solutions exists and labelled as to be closed soon label Jan 22, 2024
@relu91
Copy link
Member Author

relu91 commented Jan 22, 2024

Call 22/01:

  • Group ok for closing

@relu91 relu91 closed this as completed Jan 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
propose closing Solutions exists and labelled as to be closed soon
Projects
None yet
Development

No branches or pull requests

3 participants