Ratification
Kris Kowal
up in person at MetaWeb HQ in San Francisco. In one of the
conversations I had with Ryan Dahl, he pointed out that we have a
perception problem with CommonJS from outside the discussion list that
is driving people away from the conversation. That is the concept of
ratification.
I have to take personal responsibility for this; I started versioning
and labeling proposals as ratified to answer the problem that people
outside the list had very little way to tell how close we were to
consensus on particular proposals so they could fire the gun to
implement support for those features. The rule I've been following
for "ratification" and blessing proposals with a version number is
that all *current* participants in the discussion arrived at a point
where there were no further objections that could not be fixed
responsibly in a future version, and that there were enough
participants in the discussion to constitute a quorum. Vaguely.
I'm told that this has led to people dismissing CommonJS as a lost
cause. This is a problem. When people approach CommonJS and perceive
that they have more expertise than we do, it is imperative that these
people be encouraged to participate in the discussion. This results
in two good things: experts can educate us, and we can educate these
people in the expertise our proposals have accumulated.
So we have a tension between encouraging implementation and
encouraging continued discussion. This is not a particular surprise.
Ryan would prefer that we posed exclusively as a discussion group that
only makes proposals. Others have mentioned that we should ratify
proposals so that they are comfortable implementing them.
I've given this some additional thought. I would like to remove the
"ratification" labels and leave the version numbers in place. Instead
of having a "ratified" status, I propose that we put a table at the
header of every proposal. This would show two things: the show of
hands, and the list of implementations.
I'm looking for either a go-ahead to do this myself and permission for
anyone to help with this transition on the wiki.
Kris Kowal
Kris Zyp
On 2/1/2010 12:43 PM, Kris Kowal wrote:
> I've given this some additional thought. I would like to remove the
> "ratification" labels and leave the version numbers in place. Instead
> of having a "ratified" status, I propose that we put a table at the
> header of every proposal. This would show two things: the show of
> hands, and the list of implementations.
>
> I'm looking for either a go-ahead to do this myself and permission for
> anyone to help with this transition on the wiki.
>
That sounds good to me. I'm certainly not a PR expert, but the level of
expressed support and implementation status seems more pertinent than a
label anyway.
--
Thanks,
Kris
Kevin Dangoor
I've given this some additional thought. I would like to remove the
"ratification" labels and leave the version numbers in place. Instead
of having a "ratified" status, I propose that we put a table at the
header of every proposal. This would show two things: the show of
hands, and the list of implementations.
I'm looking for either a go-ahead to do this myself and permission for
anyone to help with this transition on the wiki.
This is a fantastic plan. It really is truer to how things run around here anyway - how many people here are behind an idea, and how many people have actually coded it up.
Actually, I would put implementations at a level above "show of hands". Once folks have conceptually agreed upon things to the point where we've got multiple implementations, perhaps the show of hands can move down elsewhere in the file just as a historical reference.
Kevin
--
Kevin Dangoor
work: http://labs.mozilla.com/
email: k...@blazingthings.com
blog: http://www.BlueSkyOnMars.com
Daniel Friesen
> ...
> I've given this some additional thought. I would like to remove the
> "ratification" labels and leave the version numbers in place. Instead
> of having a "ratified" status, I propose that we put a table at the
> header of every proposal. This would show two things: the show of
> hands, and the list of implementations.
>
> I'm looking for either a go-ahead to do this myself and permission for
> anyone to help with this transition on the wiki.
>
> Kris Kowal
>
display that information in a combined form on another page too.
~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]
Kris Kowal
<nadir.s...@gmail.com> wrote:
> If you do that using a template using a consistent format, I can make it
> display that information in a combined form on another page too.
>
> ~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]
Would you mind making the template and altering the Modules/1.1
proposal to make use of it as an example?
Kris Kowal
mob
Sounds good. Version numbers are essential for the specs and actual
implementations matter most of all. We also need some understanding
about how to evolve these versioned specs over time.
[Start rant]
There has been some "sniping" from the side-lines. It is very easy for
critics to throw general criticisms and half-specified proposals
around. The fact is that creating simple, elegant, flexible, clean
APIs is hard work and often "experts" on the sidelines will find it
just as hard when they try to get something that works outside their
own sandbox. All criticism is very, very welcome. But it is most
constructive when the voice of dissent invests some time and energy to
propose a detailed solution.
[end rant]
I think the current mechanism where proposals must be created and
championed is the right one. It allows anyone to propose and drive a
portion of a Common API through to some level of specification. Of
course it must get used and adopted. We do want the right optics and
the current specs are not ratified in any real sense except to the
level that they are implemented by real products.
So implementations matter most of all and we have to accept that
convergence takes time. Sometimes this can be done via APIs ahead of
time. Sometimes it takes implementations to lead and for us to see
what works best in practice. Server-side JS is currently experiencing
a lot of strong opinion. That is good, we'll see over time what
solutions really work. What is important for CommonJS is that we
progressively extract and promote a solid foundation and the
implementations try converge where possible.
-mob
Daniel Friesen
I'll be able to do these things in transit...
Could you add the show of hands and implementations to the top of that
page. I can't find them.
Wes Garland
Thanks for having that conversation with Ryan, and Ryan, thanks for taking the time to voice your concerns. As someone both implementing and innovating in the server-side JS community, your input is extremely valueable to this group.
I think the insight gleaned with respect to the perception problem from outside the group is key to help us better direct the group on a go-forward basis.
I, too, have found the proposal / acclamation process distressing, although perhaps from a different angle. I have been frustrated with two major issues over the course of the last year:
- Revisiting "closed" issues ad nauseum
- Putting the cart before the horse
I am used to developing software systems by compartmentalizing functionality, achieving basic functionality, experimenting, and performing step-wise refinement. The more recent efforts -- fs-base and Binary/X are actually moving better in this regard, IMHO.
I recognize that both of my frustrations are problematic in the context that you've presented from your discussion with Ryan.
I have to take personal responsibility for this; I started versioning
and labeling proposals as ratified to answer the problem that people
outside the list had very little way to tell how close we were to
consensus on particular proposals so they could fire the gun to
implement support for those features.
I've certainly argued -- vehemently -- in favour of having something I could "fire the gun" at. I think the work you've done here has been outstanding from the group's POV, even if not entirely successful from a marketing POV.
When people approach CommonJS and perceive
that they have more expertise than we do, it is imperative that these
people be encouraged to participate in the discussion. This results
in two good things: experts can educate us, and we can educate these
people in the expertise our proposals have accumulated.
You're darned right. I have asked people with significant expertise to contribute in the past -- seldom do I hear anything back. There are a lot of great minds out there that I would love to hear from.
So we have a tension between encouraging implementation and
encouraging continued discussion. This is not a particular surprise.
Ryan would prefer that we posed exclusively as a discussion group that
only makes proposals. Others have mentioned that we should ratify
proposals so that they are comfortable implementing them.
Ryan makes a good point here, although that leaves the question, "how do we know when a proposal is 'done'"? That's an important question for the implementors out there.
I would like to offer a counter proposal that slight extends our role: we serve instead as a group which
- Fosters Discussion
- Makes Proposals
- Manages the proposal namespace
- Manages the SecureableModule require() namespace (SMRNS)
Do test suites figure into this role? Maybe we should add a name like "binaryb" to SMRNS once a test suite exists; then implementors and early adopters have something to hang their hats on: if require('binaryb') works, then that must be a module which intends to pass the CommonJS-group-published binaryb test suite.
I've given this some additional thought. I would like to remove the
"ratification" labels and leave the version numbers in place. Instead
of having a "ratified" status, I propose that we put a table at the
header of every proposal. This would show two things: the show of
hands, and the list of implementations.
This seems like a good idea. But, what do we call it when we close a specification's discussion, then? We *still* need to have some kind of steady state, otherwise there is no point in listing implementations.
I'm not advocating a steady state where no discussion exists, mind you -- just fork the "closed" spec document, something like what has happened with binary/[bcde]. Or even fs-base, which, BTW, I think was a smashing success in terms of implementor unification.
Wesley W. Garland
Director, Product Development
PageMail, Inc.
+1 613 542 2787 x 102
Kevin Dangoor
This seems like a good idea. But, what do we call it when we close a specification's discussion, then? We *still* need to have some kind of steady state, otherwise there is no point in listing implementations.
One note about this: I'm not sure discussion should generally be considered "closed for a spec". Unless you're talking about a specific version of a spec. This is software and, as such, it is a living thing that will move forward, even revisiting things that have previously been "decided".
We did, as a group, agree that Semantic Versioning is a good idea, and I think we can stick to that as a way to make it clear what we're discussing (a minor addition to fs-base? a backwards incompatible change? etc.)
But, there does need to be some point at which a specific version is "tagged". To some extent, this is what I had in mind with the commonjs website in github. If we migrate things from the wiki to there when they are "tagged", then it will be clear that the next bit of discussion on a topic is going to use that as a base, at the very minimum.
I'm not advocating a steady state where no discussion exists, mind you -- just fork the "closed" spec document, something like what has happened with binary/[bcde]. Or even fs-base, which, BTW, I think was a smashing success in terms of implementor unification.
Yes, exactly!
Though we're trying to backpedal on the "ratified" status, we do still need some way to denote that we've tagged a version of a spec. That could be based on how many implementations of the spec there are. As metrics go, the fact that N people have decided to implement something in their compatible systems is a reasonable sign of support.
So, discussion is free to continue on any specs, it's just a question of what is used as a baseline for those discussions.
Wes Garland
"tagged" is much better vocabularly than "closed". When I used the word closed, "tagged" as in CVS tagging is *exactly* what I meant.
Thanks for helping me express that idea better.
And you're right, we could be using semantic versioning to discuss specifications. I had only thought of it in the context of querying libraries to find out what they had, but of course it applies in the larger picture.
mob
+1 for SemVer.
We use it in the Package spec for packages and using it for the specs
themselves conveys a lot of meaning. (the right meaning)
-mob
Thomas Aylott
The CommonJS user would be the de-facto "official" source.
That user could add all ML participants as committers.
Anyone else can fork and add their own proposals.
etc…
All major JavaScript stuff seems to be using GitHub.
Sure, a wiki works too. But it's far too vague and unorganized imho.
— Thomas Aylott
SubtleGradient
MooTools
On Mon, Feb 1, 2010 at 2:43 PM, Kris Kowal <kris....@cixar.com> wrote:
Kevin Dangoor
This is where using GitHub would solve a lot of issues.
The CommonJS user would be the de-facto "official" source.
That user could add all ML participants as committers.
Anyone else can fork and add their own proposals.
etc…
We have talked about this in the past. FWIW, the current notion is that specs start in the wiki because of the ease of collaboration and then move into git when they're "done" (tagged).
Kevin
Wes Garland
This is where using GitHub would solve a lot of issues.
Does GitHub have a git-versioned wiki and editor?
If not, Google Code's wiki is versioned with Mercurial, and you can clone a project, like forking in GitHub.
...FWIW... I think the current system isn't *too* bad, but then, I've been posting diff links in here :/
Micheil Smith
- Micheil.
> --
> You received this message because you are subscribed to the Google Groups "CommonJS" group.
> To post to this group, send email to comm...@googlegroups.com.
> To unsubscribe from this group, send email to commonjs+u...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/commonjs?hl=en.
Kris Kowal
someone has the time to help convert them to a format that Git
supports. These include ReStructured Text and Markdown. RST is a
great format for specifications, but I don't see a port to JavaScript
in the near term, which would be nice. We already have a CommonJS
Markdown parser formatter.
Kris Kowal
Wes Garland
I don't see any value in moving the wiki to any place which does not allow cloning/merging.
"Being on GitHub" is not a feature here IMO, only a possible means to an end. Having a stable URL is a feature, though.
The current wiki works well enough, it's only failing is that you can't clone/merge it. Google Code's wiki *does* support those features, but I find the wiki markup a little light for my taste.
Wes
--
You received this message because you are subscribed to the Google Groups "CommonJS" group.
To post to this group, send email to comm...@googlegroups.com.
To unsubscribe from this group, send email to commonjs+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/commonjs?hl=en.
Micheil Smith
- Micheil