search

webxdc / website

short introduction to webxdc, links to examples and docs
https://webxdc.org
8 stars 6 forks source link

Versioning the webxdc spec and adding a changelog #81

Open hpk42 opened 1 month ago

hpk42 commented 1 month ago

Brought up from @singpolyma and also been under consideration elsewhere.

It would be useful to start versioning the spec and having a changelog.

I don't have a ready suggestion but do intend to care for this during july if nobody beats me to it.

Relatedly, i intend to chat with @ansuz about evolving the webxdc spec :)

Simon-Laux commented 1 month ago

The closest thing we currently have for version is the changelog of the typescript types package: https://github.com/webxdc/webxdc-types/blob/main/CHANGELOG.md

If you want some historical stuff instead of just making a version one and only recording future changes. I think it's fine to just start recording future changes as the webxdc community is still small, maybe start before realtime channels, idk.

While I agree with making a changelog, I believe we should recommend to test if api's are available instead of some version number and try not to break existing apis. Like I'd like to avoid a getWebxdcVersion api for testing what apis are available if we can.

hpk42 commented 1 month ago

(nb. i fixed the link in your reply) The question of how to detect supported features from webxdc apps i consider as a separate issue.

Versioning of webxdc spec and changelog here is meant to support implementors so they get a way to talk and reference it in other docs like "Support webxdc.sendupdate() function as defined in webxdc-spec-1.3". And the changelog should be human-readable for implementors and webxdc app developers.