Subject: I-D source control

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 18 Nov 2011 11:48:00 +0800

It seems to be a little-known fact that we have source control
(Subversion) for WG drafts:

http://trac.tools.ietf.org/misc/venue/wiki/IetfSpecificFeatures

I'd be curious how many working groups are using this, what their
experience has been, and ways to encourage wider use (I can think of
many scenarios when source control would be very helpful, e.g., if
editors disappear).

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Thu, 17 Nov 2011 19:50:02 -0800

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of Peter Saint-Andre
> Sent: Thursday, November 17, 2011 7:48 PM
> To: Working Group Chairs
> Subject: I-D source control
> 

I've been keeping my drafts in XML form in local RCS repositories for quite some time.  It's proven extremely valuable.  I like this even better because now submitting something could in theory be as simple as telling the datatracker to post the latest version after extracting it locally and then running it through xml2rfc.

Too bad we picked SVN though.  :-)

-MSK

---

From: Leif Johansson <[email-masked]>
Date: Fri, 18 Nov 2011 04:50:40 +0100

On 11/18/2011 04:48 AM, Peter Saint-Andre wrote:
> experience has been, and ways to encourage wider use (I can think
> of many scenarios when source control would be very helpful, e.g.,
> if editors disappear).

I *don't* want this to escalate into a VCS war but I find SVN, CVS
and similar "older" VCSen less useful since they don't allow me to
usefully work offline.

	Cheers Leif

---

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 18 Nov 2011 11:58:39 +0800

On 11/18/11 11:50 AM, Leif Johansson wrote:
>>  experience has been, and ways to encourage wider use (I can
>> think of many scenarios when source control would be very
>> helpful, e.g., if editors disappear).
> 

I don't particularly care about the tool (everyone has their
preferences), but I do care about having WG documents under source
control so that it is easier to assign new editors if needed, recover
from catastrophic hardware failures by document editors, etc. I plan
to strongly encourage my WG chairs to get their WG items under source
control.

Peter

- -- 
Peter Saint-Andre
https://stpeter.im/

---

From: Yoav Nir <[email-masked]>
Date: Fri, 18 Nov 2011 06:23:19 +0200

On Nov 18, 2011, at 11:50 AM, Leif Johansson wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 

If you think this makes it hard to work offline, you should try ClearCase. On second thought, no, you shouldn't.

In CVS and SVN, you can checkout a file to your own computer, and you have no need for network connectivity until you need to commit it.

I understand that you're missing the entire history of the universe downloaded to your laptop like in git, and that this is useful in real code, but if you're editing version 12 of the draft to produce version 13, do you really need the history of the changes between version 6 and version 7?

Yoav

---

From: Leif Johansson <[email-masked]>
Date: Fri, 18 Nov 2011 05:33:33 +0100

> I understand that you're missing the entire history of the universe
> downloaded to your laptop like in git, and that this is useful in
> real code, but if you're editing version 12 of the draft to produce
> version 13, do you really need the history of the changes between
> version 6 and version 7?

I miss the ability to do operations on my repository offline, yes.

---

From: Paul Kyzivat <[email-masked]>
Date: Fri, 18 Nov 2011 12:55:24 +0800

> to strongly encourage my WG chairs to get their WG items under source

I know its minimal, old school, but we already have source control over 
drafts: draft-foo-00, draft-foo-01, ...

What's lacking is that its not versioning the *source*.
But if every version was submitted in xml form, it would be.

That may not be sufficient for large documents that get extensive 
editing before submitting a new version. Especially if there are 
multiple people editing the doc. Another form of source control might be 
helpful there.

	Thanks,
	Paul

---

From: Brian Rosen <[email-masked]>
Date: Fri, 18 Nov 2011 00:35:01 -0500

But that's pretty unusual.  It happens, but <1%.

BTW, there isn't any obvious way to fetch the xml if its there.  If you know the file name pattern, it's fairly easy, but it's not obvious.

Brian
On Nov 17, 2011, at 11:33 PM, Leif Johansson wrote:

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
> 
> iEYEARECAAYFAk7F4B0ACgkQ8Jx8FtbMZnd7XwCfTAZjMBIovyLdVHKl5bq9Xk+p
> xrgAoJOTP3KmGR+tC9N+mHZhNNdgIk3f
> =Jleu
> -----END PGP SIGNATURE-----

---

From: "James M. Polk" <[email-masked]>
Date: Thu, 17 Nov 2011 23:46:52 -0600

At 10:55 PM 11/17/2011, Paul Kyzivat wrote:
>I know its minimal, old school, but we already have source control 
>over drafts: draft-foo-00, draft-foo-01, ...
>

don't make me give up my text editor!!!!

There should be tools for those that want to use them, not imposed on 
those that don't want to use them.

IETF should only care about the format of the submissions, not how 
the formatting was done.

James

>multiple people editing the doc. Another form of source control 
>might be helpful there.
>
>         Thanks,
>         Paul

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 18 Nov 2011 14:25:41 +0800

The 6LoWPAN and CoRE have been on RFC2629-XML in the SVN religiously, and I'd never allow a WG I chair to do their stuff in a different way.
(I still have the scars from editing RFC 3095 without VC.)

For those who prefer 3rd gen VCS:  git-svn is your friend.

Maybe we should have a segment on document production in one of the next WG-Chair training sessions.

Grüße, Carsten

---

From: Paul Kyzivat <[email-masked]>
Date: Fri, 18 Nov 2011 19:41:33 +0800

On 11/18/11 1:46 PM, James M. Polk wrote:
> IETF should only care about the format of the submissions, not how the
> formatting was done.

That's fine if its what you want. In that case the .txt *is* the source.
But if the source is xml then IMO that's what you ought to submit.

	Thanks,
	Paul

---

From: Tony Hansen <[email-masked]>
Date: Fri, 18 Nov 2011 09:18:32 -0500

> many scenarios when source control would be very helpful, e.g., if

If people use either xml or nroff source for their I-D, it can be 
uploaded at the same time as the I-D itself; combined with the 
past-documents kept at tools.ietf.org, you can get a full history kept 
in our I-D archives. Plus, it's not tied to a working group, so can be 
used with any I-D.

Better? Worse? YMMV

     Tony Hansen

---

From: Tony Hansen <[email-masked]>
Date: Fri, 18 Nov 2011 10:00:18 -0500

Here's a suggestion for the I-D upload tool:

*) provide an "other" category for the source that has been kept in some 
other format than xml or nroff.

This would allow capturing source for those who use tools other than xml 
or nroff.

Another suggestion for the I-D upload tool:

*) separate out the form fields slightly to make it more obvious which 
formats are the display version of the I-D and which formats are the 
source formats. For example, instead of the current

     Upload a draft
     .txt format *  |======| Browse
     .xml format  |======| Browse
     .pdf format  |======| Browse
     .ps format  |======| Browse

it could have:
     Upload a draft
     .txt format *  |======| Browse
     .pdf format  |======| Browse
     .ps format  |======| Browse
     Source files:
     .xml format  |======| Browse
     .nr format  |======| Browse
     other format  |======| Browse

or something like that.

Another suggestion:

*) allow an author, WG chair or AD to somehow upload the source files 
for an I-D whose source file had NOT been uploaded.

     Tony Hansen

---

From: Paul Kyzivat <[email-masked]>
Date: Fri, 18 Nov 2011 23:52:40 +0800

This WFM.

I presume its been possible all along, but how does one discover and 
download forms other than the .txt form of a draft?

	Thanks,
	Paul

---

From: Tony Hansen <[email-masked]>
Date: Fri, 18 Nov 2011 11:38:37 -0500

For current sources, you can ftp to the I-D repository and see what's there.
Or you can check for http://tools.ietf.org/id/draft-something-##.xml.

     Tony Hansen

---

From: "James M. Polk" <[email-masked]>
Date: Fri, 18 Nov 2011 16:57:18 -0600

>But if the source is xml then IMO that's what you ought to submit.

I agree with this

James

---

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 19 Nov 2011 08:54:23 +0800

> Or you can check for http://tools.ietf.org/id/draft-something-##.xml.

Or (this is a bit of a workaround, too, but in some cases quite illustrative)
you can use an incomplete URL at the tools repository, and get a list of all
matching drafts, with an indication of the formats available.  Try for
instance this:

    http://tools.ietf.org/id/draft-ietf-v6ops-

I'll see if I can add a source link at the top of the htmlized draft versions,
too.

Best regards,

	Henrik

---

From: Paul Kyzivat <[email-masked]>
Date: Sat, 19 Nov 2011 09:07:33 +0800

> I'll see if I can add a source link at the top of the htmlized draft

That would be great!

	Thanks,
	Paul

---

From: Benoit Claise <[email-masked]>
Date: Sat, 19 Nov 2011 02:24:08 +0100

Henrik,
> I'll see if I can add a source link at the top of the htmlized draft 
That would be very helpfull to point to the source when we like the .txt 
output, and we want to cut/paste the xml/nroff syntax without having to 
learn all the details. I have specifically newcommers in mind here.

Regards, Benoit.

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 18 Nov 2011 18:41:30 -0800

We use it extensively in HTTPbis.

--
Mark Nottingham
http://www.mnot.net/

---

From: Yoav Nir <[email-masked]>
Date: Sat, 19 Nov 2011 08:30:01 +0200

> I'll see if I can add a source link at the top of the htmlized draft versions,

Very nice, Henrik. And speaking of htmlized versions, I see that drafts whose last version in from 2009 to mid-2010 have an html version similar (but not exactly the same as) the HTML output of xml2rfc. Can we have those back?

Thanks

Yoav

---

From: Henrik Levkowetz <[email-masked]>
Date: Sun, 27 Nov 2011 00:38:48 +0100

Hi Yoav,

> On Nov 19, 2011, at 1:54 AM, Henrik Levkowetz wrote:
...
>> I'll see if I can add a source link at the top of the htmlized
>> draft versions, too.
> 
> Very nice, Henrik. And speaking of htmlized versions, I see that
> drafts whose last version in from 2009 to mid-2010 have an html
> version similar (but not exactly the same as) the HTML output of
> xml2rfc. Can we have those back?

Those were generated by trying to apply xml2rfc to submitted xml
sources, when available.  I've now updated the scripts to use the
new xml2rfc version, and generate html files when possible.  I've
also added a link to the xml and html files to the htmlized draft
pages.  Those links will appear gradually, as the corpus is updated
(doing the htmlization is sufficiently heavy that I don't do it on
the fly, and I keep the cached versions for some time before re-
converting).

Best regards,

	Henrik

---

From: Yoav Nir <[email-masked]>
Date: Sun, 27 Nov 2011 08:33:31 +0200

Cool! Thanks