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

[Stephen Farrell <[e-mail]>]

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

On 05/16/2013 09:44 AM, Nat Sakimura wrote:
> 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
>