Using GitHub for specification development

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

Using GitHub for specification development

Robin Berjon-2
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


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Gregg Kellogg
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
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Sandro Hawke
In reply to this post by Robin Berjon-2
On Wed, 2011-11-09 at 16:34 +0100, 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?

I think it's a brilliant step in the right direction.   Excellent.

The git-vs-hg pain is my biggest worry, but we wont be alone in that.

     -- Sandro



Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Norman Walsh
In reply to this post by Robin Berjon-2
Robin Berjon <[hidden email]> writes:
> 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).

Github also has an "enterprise" product that (it appears) would allow
W3C to have their own github setup. That would have all the tecnical
advantages, I assume, but might lack the social advantage of being at
github. If that's important.

                                        Be seeing you,
                                          norm

--
Norman Walsh <[hidden email]> | To create a little flower is the labour
http://nwalsh.com/            | of ages.-- Blake

attachment0 (192 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
On Nov 9, 2011, at 17:13 , Norman Walsh wrote:

> Robin Berjon <[hidden email]> writes:
>> 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).
>
> Github also has an "enterprise" product that (it appears) would allow
> W3C to have their own github setup. That would have all the tecnical
> advantages, I assume, but might lack the social advantage of being at
> github. If that's important.

Ah, I couldn't find it last I looked but this was just released last week. That being said, losing the social side is IMHO a serious downside, and I'm rather confident that $5k for 20 users is slightly over the W3C's budget :)

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Stéphane Corlosquet
In reply to this post by Robin Berjon-2
Hi Robin,

On Wed, Nov 9, 2011 at 10:34 AM, Robin Berjon <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
In reply to this post by Gregg Kellogg
On Nov 9, 2011, at 17:02 , Gregg Kellogg wrote:
> 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).

Sexy!

So it seems there's precedent — clearly I should've moved first and asked later ;-)

How do you handle contributions? I know you're a CG but it still matters. If I, who isn't on the CG, make a pull request including a substantive change, what happens? Do you ask me to join? Or to sign an RF commitment? Has it simply not happened?

Concerning the issue tracker, I think that syncing to W3C (or using only W3C) is a hard requirement. GitHub could be taken over by $evil, or could simply go belly up overnight, and we really shouldn't lose WG work over that. That said, they have an API for almost everything, including issues, so it should be very much doable to sync.

What do you use for your bot notifications, hooks?

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Stéphane Corlosquet


On Wed, Nov 9, 2011 at 11:25 AM, Robin Berjon <[hidden email]> wrote:

Concerning the issue tracker, I think that syncing to W3C (or using only W3C) is a hard requirement. GitHub could be taken over by $evil, or could simply go belly up overnight, and we really shouldn't lose WG work over that. That said, they have an API for almost everything, including issues, so it should be very much doable to sync.

We've had the same conversation about a year ago when we moved to W3 XG on what to do with the GitHub issues. We decided to move them all to the W3 tracker and only use the W3 tracker from then onwards (we only had 8 at the time so the manual process wasn't too hard). The rationale was similar to what you outlined, and also because we didn't want to have to monitor issues in two places...

Steph.
Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Gregg Kellogg
In reply to this post by Robin Berjon-2
On Nov 9, 2011, at 8:25 AM, Robin Berjon wrote:

> On Nov 9, 2011, at 17:02 , Gregg Kellogg wrote:
>> 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).
>
> Sexy!
>
> So it seems there's precedent — clearly I should've moved first and asked later ;-)

In our case, the JSON-LD effort started out as it's own project and only later became a CG, so we've inherited the workflow.

> How do you handle contributions? I know you're a CG but it still matters. If I, who isn't on the CG, make a pull request including a substantive change, what happens? Do you ask me to join? Or to sign an RF commitment? Has it simply not happened?

Hasn't really come up yet. Few people make substantive contributions, and they're typically granted write permission to the repo, although at an early state there's usually a pull request. It's a public repo, so anyone can clone and make pull requests. So far, direct contributions have come only from CG members. Our policy should be to require CG membership before any direct contributions are made.

> Concerning the issue tracker, I think that syncing to W3C (or using only W3C) is a hard requirement. GitHub could be taken over by $evil, or could simply go belly up overnight, and we really shouldn't lose WG work over that. That said, they have an API for almost everything, including issues, so it should be very much doable to sync.

Yes, we should definitely go in this direction. Syncing GitHub issues and comments to W3 Tracker should be fairly easy (just a simple matter of programming :P).

> What do you use for your bot notifications, hooks?

The GitHub project admin has a post-receive hook that triggers a PHP (utils/git.php) that does a site update whenever a change is made. There's also an IRC setting that automatically posts to the specified server, port and channel for every update.

Come on in, the water's great!

Gregg

> --
> Robin Berjon - http://berjon.com/ - @robinberjon
>


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Karl Dubost-5
In reply to this post by Stéphane Corlosquet
Is there a way in github to associate an ISSUE number with a commit?
There is no action item too. How did people replace that.

slightly off-topic

Le 9 nov. 2011 à 11:33, Stéphane Corlosquet a écrit :
> We decided to move them all to the W3 tracker and only use the W3 tracker from then onwards (we only had 8 at the time so the manual process wasn't too hard).

I have seen that discussion a few times already.
We are always talking about user data portability and "its social graph". :p
And we seem to be unable to deal with distributed issues system. I wish we
had a shared protocol/format/issues for these.

--
Karl Dubost - http://dev.opera.com/
Developer Relations & Tools, Opera Software


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Aryeh Gregor-4
In reply to this post by Gregg Kellogg
On Wed, Nov 9, 2011 at 11:02 AM, Gregg Kellogg <[hidden email]> wrote:
> 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).

I also mirror the HTML Editing APIs specification to github, in
addition to the primary location on dvcs.w3.org:

https://github.com/ayg/editing

So far I've only gotten one pull request, and in that case I fixed the
problem by rewriting it independently anyway (for stylistic reasons).
If I got a pull request that I actually wanted to accept, I'd make
sure to get the submitter to agree to the CLA first.  This is similar
to how many open-source projects require contributors to make license
agreements.

hg-git has turned out to work just fine.  I develop locally in git,
then use a publish script to convert to hg and push to dvcs.w3.org, as
well as to github.

I've disabled the github issue tracker in favor of the W3C Bugzilla,
since I want all issues in one place, and I'd prefer that that place
be the W3C, and I'm used to Bugzilla.

Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Gregg Kellogg
In reply to this post by Karl Dubost-5
On Nov 9, 2011, at 11:29 AM, Karl Dubost wrote:

> Is there a way in github to associate an ISSUE number with a commit?
> There is no action item too. How did people replace that.

See Github flavored markdown: http://github.github.com/github-flavored-markdown/

You can mark commits and issues within the issue tracker. According to http://stackoverflow.com/questions/1687262/link-to-github-issue-number-with-commit-message, you can also do this in commit messages. So, you could do a commit with "Closes #1" and it would link to that issue and close the issue.

Typically, I usually do the commit and then close the issue. In which case, I really should mark add the commit ID to the issue when closing it. Of course, this can be done after the fact.

For action items, we usually note them in the IRC log and then someone manually creates the issue. Better workflow would be to auto-detect ACTION to raise an issue, and detect referenced issues when processing the IRC and add comments to the issue. This could also implement the "Closes #1" type behavior when issues are RESOLVED in IRC.

Gregg

> slightly off-topic
>
> Le 9 nov. 2011 à 11:33, Stéphane Corlosquet a écrit :
>> We decided to move them all to the W3 tracker and only use the W3 tracker from then onwards (we only had 8 at the time so the manual process wasn't too hard).
>
> I have seen that discussion a few times already.
> We are always talking about user data portability and "its social graph". :p
> And we seem to be unable to deal with distributed issues system. I wish we
> had a shared protocol/format/issues for these.
>
> --
> Karl Dubost - http://dev.opera.com/
> Developer Relations & Tools, Opera Software
>


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Norman Walsh
In reply to this post by Karl Dubost-5
Karl Dubost <[hidden email]> writes:
> Is there a way in github to associate an ISSUE number with a commit?
> There is no action item too. How did people replace that.

I did a commit the other day which read "Resolve issue #21, ..." and
it turned up automatically as a comment on issue 21, which I thought
was pretty awesomely slick.

                                        Be seeing you,
                                          norm

--
Norman Walsh
Lead Engineer
MarkLogic Corporation
Phone: +1 413 624 6676
www.marklogic.com

attachment0 (192 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
In reply to this post by Stéphane Corlosquet
Hi Stéphane,

On Nov 9, 2011, at 17:25 , Stéphane Corlosquet wrote:
> 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.

The current README doesn't have very strong requirements: https://github.com/webid-community/webid-spec/blob/master/README.txt. Is there another one (I'd like to copy from it :).

> 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).

So essentially you've been maintaining this manually? Do you have some form of local script to do that that one could run as a cron job?

> 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 don't think that that's a strong policy, it seems that the WebApps WG has been putting its specs at the hg root level and not under their group's directory (which is meant for tests).

> I didn't think using branches was a good solution here.

No, indeed it wouldn't be!

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
In reply to this post by Karl Dubost-5
On Nov 9, 2011, at 20:29 , Karl Dubost wrote:
> And we seem to be unable to deal with distributed issues system. I wish we
> had a shared protocol/format/issues for these.

Could this provide a useful starting point?

  http://develop.github.com/p/issues.html

It looks like it could map onto the W3C model relatively easily.

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
In reply to this post by Aryeh Gregor-4
On Nov 9, 2011, at 20:55 , Aryeh Gregor wrote:
> I also mirror the HTML Editing APIs specification to github, in
> addition to the primary location on dvcs.w3.org:

So it seems that everyone's doing it, people just weren't sharing :) Cool!

> hg-git has turned out to work just fine.  I develop locally in git,
> then use a publish script to convert to hg and push to dvcs.w3.org, as
> well as to github.

Care to share the script?

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
In reply to this post by Gregg Kellogg
On Nov 9, 2011, at 21:20 , Gregg Kellogg wrote:
> For action items, we usually note them in the IRC log and then someone manually creates the issue. Better workflow would be to auto-detect ACTION to raise an issue, and detect referenced issues when processing the IRC and add comments to the issue. This could also implement the "Closes #1" type behavior when issues are RESOLVED in IRC.

Note that on GitHub you can assign an issue to someone. This is their equivalent of an action and if you pause to think about it it actually makes sense: if someone needs to do something it's that there's a problem of some sort to fix :) You can also mention someone in an issue, and that will show up in the UI.

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Robin Berjon-2
In reply to this post by Robin Berjon-2
On Nov 9, 2011, at 16:34 , Robin Berjon wrote:
> 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.

FWIW I put it up at:

    http://scriptlib-cg.github.com/api-design-cookbook/

The repository can be forked, etc. from:

    https://github.com/scriptlib-cg/api-design-cookbook

I haven't yet set up syncing to hg, I was hoping that Aryeh would send me his script so that I could be lazy about it (the target hg repo already exists).

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: Using GitHub for specification development

Aryeh Gregor-4
In reply to this post by Robin Berjon-2
On Thu, Nov 10, 2011 at 6:21 AM, Robin Berjon <[hidden email]> wrote:
> On Nov 9, 2011, at 20:55 , Aryeh Gregor wrote:
>> hg-git has turned out to work just fine.  I develop locally in git,
>> then use a publish script to convert to hg and push to dvcs.w3.org, as
>> well as to github.
>
> Care to share the script?

http://dvcs.w3.org/hg/editing/file/tip/publish

The relevant bit is:

----
cd /tmp
hg clone ~/webroot/tmp/editing hg-editing.$$
cd hg-editing.$$
hg push -r master https://dvcs.w3.org/hg/editing
cd ..
rm -rf hg-editing.$$
----

My working git copy is ~/webroot/tmp/editing, so of course you'll want
to change that (and the dvcs.w3.org URL) as appropriate.  In principle
this shouldn't be necessary -- it should be possible to keep a
persistent hg copy, pull changes from the git copy, and push them to
the central hg copy.  I recreate the hg repository every time instead,
which takes a few minutes, because I was getting cryptic errors when
pulling from the git repo to the hg clone.  I haven't had any problems
with my current technique, except that it's slow.  The commit id's
that hg-git generates seem to be consistent, so there's no problem
when pushing to the existing central repo.

You'll need to install hg-git: http://hg-git.github.com/  Once you do
that, regular commands like hg clone/pull/push will work on git
repositories as well as hg repositories, so they'll clone a git
repository into an hg repository, or push/pull changes from a git repo
to the current hg repo.  The resulting hg repositories can be used
like regular hg repositories.  I believe it's possible to convert back
to git too somehow, but I haven't tried it.  I'd guess you create an
empty git repo with git init, then use hg push to populate it or such.