Re: [OAUTH-WG] Use of Version Control Systems for Draft Editing

["Richer, Justin P." <[e-mail]>]

I have already been using an approach like this for all of the drafts that I edit, most notably the DynReg WG document and both the Introspection and Chaining individual submissions. I run everything through my GitHub repository here:

https://github.com/jricher/oauth-spec/

I use the issue tracker there to note down things that come up in the WG conversations on the list, so that when I actually do get to go edit things, I don't forget anything. Once or twice, I have gotten issues submitted directly to github, but the actual conversation around any real changes (beyond typos) always comes back to the list. I do think it would be worthwhile to connect the mailing list to the notifications of the tracker for official documents. It would be fairly easy to set up a GitHub organization that's backed by the mailing list's address for notifications, and I think other development platforms have similar capabilities.

However, I completely disagree with ODIF's decision regarding editing tools. I've made some edits to the OIDF specs myself, and I find the "plain text editor" rule to be a draconian overreaction that makes creating good edits tedious, slow, and error-prone. In my personal experience, good tools like XML Mind's XML2RFC plugin are profoundly useful, and the formatting artifacts they create are minimal and easily ignored. The diffs that are tracked in Git are *far* from useless, and if you ask me, if you want to do a *real* diff on these documents you'd use the rfcdiff anyway, which ignores the XML formatting changes and focuses on the actual content. It's not perfect either, but it's far from useless.

 -- Justin



On May 13, 2013, at 9:08 AM, Nat Sakimura <[e-mail]<mailto:[e-mail]>>
 wrote:

I am probably biased since I am the one who introduced ticket driven version control to OIDF but it proved to be very valuable especially for transparency purposes. Each changes are linked to the ticket so it is easy to see why that change was made.

As to the comments v.s. mailing list relationship is concerned, I think it is possible to forward all the comments to the list, and in case of IETF, it should do so.

One feedback on the experience we had at OIDF is that XML Editing tools changes all sort of formatting making the diff at bitbucket useless. So, we had to resort to emacs/vim/ etc.

my 2c.

Nat Sakimura




2013/5/13 Stephen Farrell <[e-mail]<mailto:[e-mail]>>

Hiya,

On 05/13/2013 09:04 AM, Hannes Tschofenig wrote:
> Hi all,
> the OpenID Connect had gained some experience with using version control systems
> for editing specifications (and the use of issue trackers), see
> http://openid.bitbucket.org/. Based on a recent discussion in the IETF (among
> the working group chairs) I am wondering what your experience is with those
> tools and whether you see value in using these tools for document editing in the
> OAuth working group.

Sounds like a fine plan if the wg want to try it. Only thing I'd
note is that it means editors need to be *very* careful to bring
discussion back to the wg list when that's needed, since you will
likely get comments in the version control environment that are
not cc'd to the wg list. (The IETF will be considering generic
solutions for that, if you're interested get involved with the
tools team.) In turn, I suspect that means that wg chairs need
to make sure there's an editor who really gets when a change needs
to be discussed on the list and when its ok to just fix a typo.

The httpbis wg have some experience doing this btw and have hit
that specific issue of comments being made on github but not the
list. There's a recent thread [1] that ends with good advice from
the wg chair.

And in case someone asks, reasons why we need the wg list cc'd
include open-ness and to be clear as to what's an IETF
contribution. There're probably more but these are enough;-)

Cheers,
S.

[1] http://lists.w3.org/Archives/Public/ietf-http-wg/2013AprJun/0334.html



> Ciao
> Hannes
>
>
>
> _______________________________________________
> OAuth mailing list
> [e-mail]<mailto:[e-mail]>
> https://www.ietf.org/mailman/listinfo/oauth
>
_______________________________________________
OAuth mailing list
[e-mail]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/oauth



--
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en
_______________________________________________
OAuth mailing list
[e-mail]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/oauth