Re: Using GitHub for specification development

We've been using GitHub to generate the JSON-LD specs [1] [2]. It has, indeed, been useful for people to enter comments in-line, and we use the GitHub issue tracker instead of the W3C tracker. What this misses is automatically updating issues based on email threads referencing the issues; but this could probably to added with a fairly simple robot.

Changes are automatically checked out to http://json-ld.org, and commits are broadcast on IRC (#json-ld on irc.freenode.net).

Gregg

[1] http://json-ld.org/spec/latest
[2] https://github.com/json-ld/json-ld.org

On Nov 9, 2011, at 7:34 AM, Robin Berjon wrote:

> Hi all,
> 
> one thing that was discussed during the "What jQuery and JS developers want from web standards" breakout session was the possibility of using GitHub for specification development.
> 
> It would have multiple advantages:
> 
>    • It allows for pull requests, which means that anyone can suggest improvement to the spec more easily.
>    • The above does make handling editorial comments a lot easier (since people can just click "edit" and propose the changes rather than make an endless list in email).
>    • It allows people to experiment with variations on a specification while it it being developed.
>    • It brings W3C closer to the core community of developers for whom GitHub is the centre of the world (anyone who has done JS development in the past few years will know what I mean).
>    • It has a coolness factor.
> 
> It requires some practical tweaking:
> 
>    • It would be unacceptable to have all the history of development of some specifications stored with a third party server, so it would have to be synced with W3C's repositories. It looks like http://mercurial.selenic.com/wiki/ConvertExtension could cover that on a cron job (or commit hook).
> 
> It would pose some challenges:
> 
>    • Pull requests would go straight to the editor. This means that we need to tread carefully with IP commitments and make sure that someone is in the loop who will double-check that substantive text isn't being integrated that isn't under RF protection.
>    • It will scare some people.
> 
> In order to avoid endless debate about whether it would be a good idea or not, whether it might fail outright or not, whether it will break the web and kill unikittens or not, I propose to make an experiment, see how it goes, and share the feedback with this list after a while so that we can make an informed, reality-based decision that doesn't involve sacrificing kittens and unicorns.
> 
> The experiment would consist in taking just one document to develop there in this way, and see if it flies. I happen to have just the candidate. All of WebApps, DAP, and at least two breakout sessions have been talking about making some kind of API design cookbook document that would help editors and people in general make good, informed decision when creating Web APIs.
> 
> The advantages of picking this document for this experimentation are:
> 
>    • It is non-normative, and so screwing up RF has limited consequences.
>    • It is close to the hearts of the community we're trying to become closer with.
>    • It isn't scary if we get it wrong, or if it gets out of hand (worst case scenario: we have a lot of documented disagreement about how to design APIs, which is a win over the current situation of having a lot of undocumented disagreement about the same).
>    • I'm already lined-up as a co-editor of this document and willing to serve as guinea pig.
> 
> So unless someone screams bloody murder I propose to go ahead and carry out this experiment (and post the relevant links here). When there's something interesting to report, I will also bring it here.
> 
> Incidentally, irrespective of whether we do the above or not, I think that GitHub would also be a great way of getting tests. JS developers could contribute tests to an "unverified" branch, and those would be merged to master as they are checked. Just a thought.
> 
> WDYT?
> 
> -- 
> Robin Berjon - http://berjon.com/ - @robinberjon
> 
>

Received on Wednesday, 9 November 2011 16:03:49 UTC