How to propose a change to the API spec

As we're moving from ideas exchange to actual spec writing, it can be 
nice to make it a little easier to track what changes people are 
proposing, and what happens to them. To this end, here's a very 
lightweight piece of process proposal. If you like it, use it.

When you want a change to the spec, please send an email to the list.
The email should contain:

Subject line: CHANGE: <one-line description of what the change is>

Body, 3 sections:

1) What you want to change - as a functional description.

Example: "Make current Codec bitrate available to the JS"

2) Why it's a good thing - if possible with references to use cases or 
examples.

Example: "Because people who monitor quality metrics for scenario 3.4.7 
from the scenarios document will need this information in their stats 
gathered on a central server"

3) Which parts of the spec are affected - at least sections; if you have 
new proposed text, that's good.

Example: "MediaStreamTrack needs an extra exposed variable called 
"bitrate" that reflects the instantaneous bitrate of the stream - that 
would go in section 4.7.33 of the Sept 34 draft".

Then we can have a discussion (and people can blow the particular 
example I used out of the water because there's no such thing as an 
instantaneous bitrate, it's a property belonging to the PeerConnection 
not the MediaStreamTrack, and so on and so forth).
Once we conclude that there's consensus on making the change, we make a 
change; if there's no consensus, we can start a new thread on a new 
change proposal.

The typical expectation should be that changes that aren't controversial 
get accepted in ~48 hours for small changes, ~1 week for more dramatic 
changes.

Normally, one of the chairs will send a note saying "I think there's 
good enough consensus to incorporate this" or equivalent to close off 
the thread; then it's up to the editors to integrate the change and make 
adjustments to the rest of the document to fit.

If there is controversy, things take longer.

At the very least, we will have a clear starting point for the discussion.
Does this make sense to people?

                      Stefan and Harald

Received on Tuesday, 27 September 2011 13:39:10 UTC