Re: Using GitHub for specification development

Hi Robin,

On Wed, Nov 9, 2011 at 10:34 AM, Robin Berjon <robin@berjon.com> 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?
>

The WebID specification [1] has been living on GitHub since its beginnings
in July 2010, and has had 6 contributors so far (see network [2]). We
actually didn't have IP issues since Manu Sporny had outlined strict
requirements for contributing to the spec in the README file. Later when
the group moved to a W3 XG, we created a mirror of this github repo on the
W3C server [3]. I've been acting as the guinea pig for maintaining these
repos in sync using the hg-git extension [4] which I run on my local
machine and then push to the appropriate remotes (sorry, I'm using
git terminology here as I'm not familiar with hg). It's been working well
so far, but the main hurdle is that the W3 one repo per group policy
conflicts with the git/github philosophy of cheap repos, so it worked well
while we just had the spec, but when we started adding a paper, then an
ontology, it became a mess... The natural way of structuring this on github
is to create a repo per project, but since we wanted to keep them on the W3
server we had to keep them in the same repo, in sub folders, which defeats
the purpose of git repos and feels like we're back in the svn era. I didn't
think using branches was a good solution here. If the W3 had a model closer
to github with the ability to have several repos per group, it alleviate
some of the pain here. Ideally, having a git hosting option on the W3 dvcs
server would make the sync'ing mechanism a no brainer.

Steph.

[1] https://github.com/webid-community/webid-spec
[2] https://github.com/webid-community/webid-spec/network
[3] https://dvcs.w3.org/hg/WebID
[4] http://hg-git.github.com/