search

w3c / media-source

Media Source Extensions
https://w3c.github.io/media-source/
Other
268 stars 58 forks source link

Add a change log to the specification #294

Open cconcolato opened 3 years ago

cconcolato commented 3 years ago

It would be good for new readers of the spec to understand what has changed in v2 compared to v1. IIUC, only changeType has been added so far. Maybe new features/corrections will be made until final publication. It would be good to have a "Change Log" section in the spec.

wolenetz commented 3 years ago

Good idea! When developing the v1 / 2016 REC spec, we used to have a changelog (manually updated, literally in the spec source), but opted eventually to let the git history explain the changes.

With work happening on v2, clarifying what precisely is new in v2 versus that previous 2016 REC spec would indeed be helpful.

As part of MSE v2 FPWD CfC, there is already some discussion around the SOTD section referring to this at a high level (e.g. this is v2, v1 was REC in 2016). Adding some text around feature areas new in v2 as well as reinforcing the existing 'commit history' link in the header with perhaps a copy of that link inline in the related v1/v2 SOTD text might help.

Currently, while many of the changes have been editorial (updates to BSF specs before they were recently split into distinct repos, updating various boilerplate sections' text, and modernizing to current ReSpec usage, for example), both changeType and the initial feature specification for MSE-in-Workers are in the v2 ED currently.

tidoust commented 3 years ago

See #296 for proposed changes to the Status of This Document section.

Listing substantive changes in this section seems good enough to me, especially as plan is to automate publication of WD afterwards whenever a commit gets pushed to the main branch.

A proper change log section can be useful too, though, e.g. with one entry per "interesting" spec statuses: FPWD, CR snapshots, REC.

wolenetz commented 3 years ago

Even with #296 landing soon, I like the idea of substantive short-lists of changes for "interesting" spec statuses as you described, @tidoust, so will keep this issue open after #296.