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

[Nat Sakimura <[e-mail]>]

I am by no means suggesting IETF to use Vim/emacs. That is counter
productive. I was merely pointing out that one has to decide the diff
policy wisely.

I like XMLMind's XML2RFC. Too bad it became commercial product only.

Intelligent diffs would work fine. However, there have been push back to
that since that made it difficult for the users that just look at the web.

In IETF, we should take the rfcdiff, IMHO, so whitespace changes in XML
should not be an issue.

Nat

2013/05/15 22:11、"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]>
 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]>

>
> 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]
> > https://www.ietf.org/mailman/listinfo/oauth
> >
> _______________________________________________
> OAuth mailing list
> [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]
https://www.ietf.org/mailman/listinfo/oauth