Subject: Draft editors getting changes from the WG using DVCS systems

From: Paul Hoffman <[email-masked]>
Date: Wed, 8 May 2013 09:35:39 -0700

Greetings again. When a WG member asks for changes in a draft, it usually does so on one of two ways:

a) Text messages that list specific changes such as "in Section 3.2, second paragraph, change the last sentence to use MUST"

b) Editing the current version of the draft to make it look like what the WG member wants, and then submitting it through a system like Git, Subversion, or Mercurial

For this thread, I'm only interested in (b), distributed version control systems. If you have folks in your WG using (b):

1) Which system do they use?

2) Are there written instructions for the steps a WG member must take to submit changes?

3) What sort of feedback are you getting?

This is not an effort to find which is "best" or to make a new IETF process, but just to see what's out there and how well documented it is.

--Paul Hoffman

---

From: Ole Troan <[email-masked]>
Date: Fri, 10 May 2013 10:22:19 +0200

> This is not an effort to find which is "best" or to make a new IETF process, but just to see what's out there and how well documented it is.

I've used git and github for quite a few drafts, but mainly between the authors rather than something used by all.
e.g. https://github.com/otroan/MAP/network
I've basically run with one owner/editor, where co-authors send a pull request.

cheers,
Ole

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 10 May 2013 07:49:06 -0700

> I've basically run with one owner/editor, where co-authors send a pull request.

Can you say more about how the co-authors send in their requests? Do they do them in their own development branches? That's not what it looks like from the network diagram above, but that diagram could be misleading.

And I'm still hoping to hear from other folks. I got two off-line responses, but this seems like a very small number of WGs using these types of tools.

--Paul

---

From: Tomek Mrugalski <[email-masked]>
Date: Fri, 10 May 2013 17:02:37 +0200

On 10.05.2013 16:49, Paul Hoffman wrote:
>> I've used git and github for quite a few drafts, but mainly between
>> the authors rather than something used by all. e.g.
>> https://github.com/otroan/MAP/network I've basically run with one
>> owner/editor, where co-authors send a pull request.
> 
> Can you say more about how the co-authors send in their requests? Do
> they do them in their own development branches? That's not what it
> looks like from the network diagram above, but that diagram could be
> misleading.
This is also used by several cases as personal repositories of DHC wg
members. Here are couple examples:

https://github.com/tomaszmrugalski/ietf-dhcpv6-fo
https://github.com/tomaszmrugalski/ietf-dhc-options
https://github.com/msiodelski/ietf-dhc-relay-dhcp4-over-dhcp6

The usage model is almost the same as Ole's. Couple interested parties,
usually co-authors have write access and they update the text based on
feedback during meetings, mailing list discussions, off the list
comments and their own ideas. Once the time is right, the snapshot from
github is uploaded to IETF. WG members discuss and comment on only on
those versions uploaded to IETF.

Using github is basically more convenient than sending candidate drafts
and changes over mails. It is also very helpful to have the ability to
who authored specific line in case of doubts or questions. For some
reason that I don't understand, git command to get this information is
called "blame".

Tomek

---

From: "Tschofenig, Hannes (NSN - FI/Espoo)" <[email-masked]>
Date: Mon, 13 May 2013 07:17:08 +0000

Hi Paul, 

I have been using Github for draft editing for some time now https://github.com/hannestschofenig/tschofenig-ids. 

A few observations I made:

* it is great tool for synchronizing data between authors
* it allows me to share the most recent snapshot (including other data like XML schema, example, etc.) with co-authors and WG members
* most IETF folks I worked with are not necessarily deeply familiar with GIT (beyond just pulling the latest version of the draft/drafts). 

The last item is particularly important when you want to work with others on a document where multiple persons contribute text. If an entire working group is supposed to work on a draft together and upload text contributions then this will require a bit of training. 

A number of other folks have used Github for their IETF drafts in the working groups I am involved in but so far we have not used it as a collaborative tool in the groups. Interestingly, folks from the Oauth WG have used a variety of different tools (including SVN) in their work on the OpenID Connect specifications but nobody so far had suggested to me that we should use the same tools in the Oauth working group as well. I will ask why nobody had made that suggestion. 

Ciao
Hannes

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of ext Tomek Mrugalski
> Sent: Friday, May 10, 2013 6:03 PM
> To: [email-masked]
> Subject: Re: Draft editors getting changes from the WG using DVCS
> systems
>

---

From: Edward Crabbe <[email-masked]>
Date: Mon, 13 May 2013 10:46:30 -0700

+1

I've used git/github for draft / spec editing on a few projects now,
entirely with coauthors rather than any wg as a whole (which sounds
'difficult').  It has all the usual benefits of an SCM and is simple
to set up and administer.

I'm not the right person to give a tutorial on this, but finding
someone to present git and source control in general following the
newcomers orientation on Sunday sounds like a fantastic idea.  ;)

---

From: Jouni Korhonen <[email-masked]>
Date: Wed, 15 May 2013 08:59:38 +0300

> newcomers orientation on Sunday sounds like a fantastic idea.  ;)

+3 ;-) This would definitely be a good idea.. though I think one
Sunday session is hardly enough to go in depth e.g. with Git. Maybe
with a well defined & limited scope that works out.

And yes, I also use SVN or Git for my own projects. Though, my
experience is only with a small group of "contributors" having
an access to the version control.

- JOuni