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

From: "Hannes Tschofenig" <[email-masked]>
Date: Mon, 13 May 2013 10:04:21 +0200 (CEST)

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.

Ciao

Hannes

---

From: Stephen Farrell <[email-masked]>
Date: Mon, 13 May 2013 10:40:34 +0100

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
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Nat Sakimura <[email-masked]>
Date: Mon, 13 May 2013 22:08:41 +0900

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 <[email-masked]>

-- 
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en

---

From: "Richer, Justin P." <[email-masked]>
Date: Wed, 15 May 2013 20:11:33 +0000

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 <[email-masked]<mailto:[email-masked]>>
 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 <[email-masked]<mailto:[email-masked]>>

Hiya,

Cheers,
S.

> [email-masked]<mailto:[email-masked]>
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

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

---

From: Nat Sakimura <[email-masked]>
Date: Thu, 16 May 2013 10:44:25 +0200

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." <[email-masked]> のメッセージ:

 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:

 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 <[email-masked]>
 wrote:

 my 2c.

 Nat Sakimura

---

From: Stephen Farrell <[email-masked]>
Date: Thu, 16 May 2013 10:00:09 +0100

Folks, please take generic discussion to the tools list. [1]
That's where it'll have some effect.

If you're only talking about what the oauth wg ought do that's
fine, but this reads as more generic.

Thanks,
S.

[1] https://www.ietf.org/mailman/listinfo/tools-discuss