Subject: Re: use of Git-hub

From: Lee Howard <[email-masked]>
Date: Wed, 02 Nov 2016 09:06:19 -0400

On 10/31/16, 8:56 AM, "WGChairs on behalf of Stewart Bryant"
<[email-masked] on behalf of [email-masked]> wrote:

>
>
>On 31/10/2016 12:48, Ray Bellis wrote:
>>
>> On 31/10/2016 10:37, Jaime Jiménez wrote:
>>> +1 to uploading markdown directly
>> Which version, or don't we care?
>>
>> I use Kramdown.  I know others use Miek Gieben's version.
>>
>> Ray
>>
>
>I also use Kramdown, but why not accept both?

Somebody has to write and maintain tools to convert every input format to
every output format. I¹m a big fan of people creating tools to parse
whatever format(s) they happen to like, but I don¹t want to assign work to
the Tools Team, and ultimately spending money on tool development. So, if
anyone here is inclined to write a parser that will take their favorite
version of markdown (or auto detect various versions) and convert it to
canonical XML, I¹m sure you would have community support (in the form of
the beverage of your choice).

Please read https://datatracker.ietf.org/doc/draft-iab-rfc-framework/

Lee

>Stewart

---

From: Eliot Lear <[email-masked]>
Date: Wed, 2 Nov 2016 14:56:49 +0100

I just want to add one additional point.  Whatever mechanisms are
implemented it is important that conversations not be fragmented in such
a way that someone is put in a position to have to participate in all
media mechanisms that a chair may wish to use in order to be part of the
consensus, as that would be antithetical to inclusiveness.  Tooling
should support any necessary connectivity to avoid that possibility.

Eliot

On 10/31/16 10:45 AM, Eliot Lear wrote:
> The issue has more to do with where one finds a record of important
> decisions AND discussions and under whose control that resides.  The
> fates of the IETF and Github are not shared.  That's a solvable
> problem, but it should be solved.
>
> Eliot
>
>
>
> On 10/29/16 2:32 AM, Kyle Rose wrote:
>> On Fri, Oct 28, 2016 at 8:08 PM, Bernard Aboba
>> <[email-masked] <mailto:[email-masked]>> wrote:
>>
>>     It seems to me that there needs to be a link between github and
>>     WG mailing lists.
>>
>>     Unless github Issue and PR notifications are forwarded to the WG
>>     mailing list, the WG will have no archive of when Issues were
>>     raised or changes were proposed. Without forwarding Merge
>>     notifications there will be no WG archive of when changes were
>>     made. Without close notifications there will be no archive of
>>     when Issues or PRs were closed.
>>
>>
>> Sure there is: the git reflog tracks all the changes and commit
>> messages along with the commit date. Starting with a single
>> invocation of "git log", you can then correlate changes and
>> discussions by date between the mailing list and github similarly to
>> how you'd have to correlate discussions across threads on the mailing
>> list. Auditing or determining what was decided when should be quite
>> straightforward.
>>
>> Furthermore, integrity guarantees are even better than those for a
>> mailing list because if someone attempts to modify the commit
>> history, everyone who's pulled a copy of that repository will notice
>> the next time they try to pull the latest commits. Changes in git are
>> protected cryptographically.
>>
>> Would copying the mailing list on changes to the master branch be too
>> much noise relative to whatever value there is in doing so? I don't
>> personally see much value since I know how to view the commit log.
>>
>> Kyle
>>
>

---

From: Stewart Bryant <[email-masked]>
Date: Wed, 2 Nov 2016 14:04:29 +0000

> Please read https://datatracker.ietf.org/doc/draft-iab-rfc-framework/

This depends on the purpose of the source format archive.

If it is to automatically RFC text you are correct, but I don't think 
that is the
purpose of it, I think of it more as a backstop archive method for the 
author team.
That being the case I am not entirely sure the tool needs to know anything
much about the format.

Stewart

---

From: Kyle Rose <[email-masked]>
Date: Wed, 2 Nov 2016 10:12:40 -0400

On Wed, Nov 2, 2016 at 9:56 AM, Eliot Lear <[email-masked]> wrote:

> implemented it is important that conversations not be fragmented in such a
> way that someone is put in a position to have to participate in all media
> mechanisms that a chair may wish to use in order to be part of the
> consensus, as that would be antithetical to inclusiveness.  Tooling should
> support any necessary connectivity to avoid that possibility.
>

I think this is overly limiting as a requirement. For small N (such as N=2:
email and github), I don't think the burden is too great to require that
people follow both. Furthermore, the whole point of using more than one
tool is that some tools are better than others for certain workflows, so
attempting to shoehorn all information flow into all paths is going to make
every mechanism less useful by introducing more noise in each.

If you're talking about an unending proliferation of chair-specific public
communication mechanisms leading to the inability of even a well-informed
person to follow it all or even know what to follow, I agree that there
should be some limits, but I recommend we wait until that is an actual
danger before trying to design a solution. Adding github to email after 30
years of IETF doesn't seem like it's putting us in danger of fragmenting
participation too much anytime soon.

Kyle

---

From: Eliot Lear <[email-masked]>
Date: Wed, 2 Nov 2016 15:40:31 +0100

On 11/2/16 3:12 PM, Kyle Rose wrote:
> On Wed, Nov 2, 2016 at 9:56 AM, Eliot Lear <[email-masked]
> <mailto:[email-masked]>> wrote:
>
>     implemented it is important that conversations not be fragmented
>     in such a way that someone is put in a position to have to
>     participate in all media mechanisms that a chair may wish to use
>     in order to be part of the consensus, as that would be
>     antithetical to inclusiveness.  Tooling should support any
>     necessary connectivity to avoid that possibility.
>
>
> I think this is overly limiting as a requirement. For small N (such as
> N=2: email and github), I don't think the burden is too great to
> require that people follow both. Furthermore, the whole point of using
> more than one tool is that some tools are better than others for
> certain workflows, so attempting to shoehorn all information flow into
> all paths is going to make every mechanism less useful by introducing
> more noise in each.

That's you.  Not everyone.  The point is that EVERYONE should be aware
of proposed changes and discussion, not SOME people who just happen to
be comfortable with the next tool du jour.  This has been done in a
reasonable way with Bugzilla, and so we have running code.  GH probably
has a similar mechanism, no?

FWIW there have been numerous trackers used over the past five years.  I
myself have used several as a chair, and one or two as an author,
including Github.

Eliot

---

From: Gorry Fairhurst <[email-masked]>
Date: Wed, 02 Nov 2016 15:10:03 +0000

On 02/11/2016 14:40, Eliot Lear wrote:
>> I think this is overly limiting as a requirement. For small N (such 
>> as N=2: email and github), I don't think the burden is too great to 
>> require that people follow both. Furthermore, the whole point of 
>> using more than one tool is that some tools are better than others 
>> for certain workflows, so attempting to shoehorn all information flow 
>> into all paths is going to make every mechanism less useful by 
>> introducing more noise in each.
>
> reasonable way with Bugzilla, and so we have running code.  GH 
> probably has a similar mechanism, no?
>
> FWIW there have been numerous trackers used over the past five years.  
> I myself have used several as a chair, and one or two as an author, 
> including Github.
>
> Eliot
+1

Gorry

---

From: Robert Sparks <[email-masked]>
Date: Wed, 2 Nov 2016 12:40:23 -0500

Just to make sure folks aren't talking past each other, there are two 
suggestions being made.

Stewart's is to allow putting .md (or .future_thing) into the repository 
the way we allow .ps to be submitted now - in _addition_ to the required 
.txt or .html). That shouldn't be hard to add support for.

Several others are suggesting allowing submission of only .md (the way 
we have started accepting submission of only .xml recently). That is the 
step Lee is pushing gently back against. It could be made to happen, and 
I think it would be a reasonable long term goal. I think we need to see 
some convergence in what the various converters currently accept first. 
The IESG would need to make sure they were as comfortable with the 
submission in that format satisfying the IPR/licensing requirements as 
they are accepting just the xml.

RjS

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 2 Nov 2016 14:13:30 -0400

For a long time I have been troubled by the submission of multiple 
formats of the "same" document. When doing so there is an implicit 
assumption that these forms are "equivalent" - generally by being 
arithmetically derived from a common source. My concern is that there is 
no guarantee that they are so related. (For instance, it wouldn't be 
hard for somebody to accidentally submit one form that was a version off 
from the others.)

This is avoided if only one form is submitted, and the tools derive all 
the other formats. This still permits a variety of submission formats, 
so long as the tools relating them are controlled and invoked by the ietf.

	Thanks,
	Paul

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 2 Nov 2016 14:23:14 -0400

We are very clear as to which form is normative (if that even means 
anything for I-Ds).  For internet-drafts, if someone deliberately 
submits differences it is either ignored or causes confusion.  Neither 
is to the benefit of the submitter.

For RFCs, with the new format, all the presentation formats will be 
derived algorithmically from the XML.  And the XML will be considered 
normative.

Yours,
Joel

---

From: Stewart Bryant <[email-masked]>
Date: Wed, 2 Nov 2016 18:46:04 +0000

I agree with Roberts assessment of the two proposals.

I do support Lee pushing back on .foo being *only* submission, but that 
was not what I proposed. Indeed because of the IPR issue, I would prefer 
that we always submitted a complete human readable version so that it 
would be difficult for the submitter to deny that they were unaware of 
the IPR statement at the front of an ID,

Stewart

On 02/11/2016 17:40, Robert Sparks wrote:
> Stewart's is to allow putting .md (or .future_thing) into the 
> repository the way we allow .ps to be submitted now - in _addition_ to 
> the required .txt or .html). That shouldn't be hard to add support for.
>
> we have started accepting submission of only .xml recently). That is 
> the step Lee is pushing gently back against. It could be made to 
> happen, and I think it would be a reasonable long term goal. I think 
> we need to see some convergence in what the various converters 
> currently accept first. The IESG would need to make sure they were as 
> comfortable with the submission in that format satisfying the 
> IPR/licensing requirements as they are accepting just the xml.
>
> RjS
>
>
>> purpose of it, I think of it more as a backstop archive method for 
>> the author team.

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 2 Nov 2016 15:08:02 -0400

> is to the benefit of the submitter.

*Today* .txt is still the authoritative format. AFAIK, if I submit both 
txt and xml then they are both archived, and trusted.

Suppose Joe Smith had submitted both xml and txt for a draft. But he 
accidentally submitted an xml that was ahead of the corresponding txt. 
(It includes possible planned changes that have not been reviewed.)

Then he gets hit by a truck and I need to take over as editor. I would 
be inclined to start from the xml. It may take awhile to figure out what 
has happened and recover.

> derived algorithmically from the XML.  And the XML will be considered

That was the plan. But now people are talking about submitting markdown 
that then must be processed to generate the xml. That puts us in the 
same boat as with xml and txt today.

	Thanks,
	Paul

---

From: Robert Sparks <[email-masked]>
Date: Wed, 2 Nov 2016 15:12:25 -0500

On 11/2/16 2:08 PM, Paul Kyzivat wrote:
> *Today* .txt is still the authoritative format. AFAIK, if I submit 
> both txt and xml then they are both archived, and trusted.
For some time now, we have allowed people to submit _only_ the .xml and 
the .txt is generated form the .xml.
> be inclined to start from the xml. It may take awhile to figure out 
> what has happened and recover.
>
> That was the plan. But now people are talking about submitting 
> markdown that then must be processed to generate the xml. That puts us 
> in the same boat as with xml and txt today.
>
>     Thanks,
>     Paul
>
>> Yours,
>> Joel
>>
>>>> repository
>>>>>> Please read 
>>>>>> https://datatracker.ietf.org/doc/draft-iab-rfc-framework/
>>>>>>
>>>>>
>>>>> the

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 2 Nov 2016 16:25:58 -0400

I am not sure I understand your point.

If we allow some other submission for RFC, then the submitters will be 
asserting that the resulting XML is what they intend.  I would be a 
little concerned about not even seeing the XML if I were the submitted, 
but it is a choice I could see us allowing at some point in the future 
(albeit with tooling and support constraints.)  But the author will 
still be reviewing either the XML or the output from the transformation 
of the XML (review procedures are still under discussion.)

For I-Ds, if folks want to do random things, I guess it is up to the 
IESG.  I know that some folks still prepare docs using nroff, and some 
folks prepare them using MS word.  So be it.

Yours,
Joel

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 2 Nov 2016 19:01:24 -0400

> the .txt is generated form the .xml.

I hadn't noticed. That is good!

Do we still allow both to be submitted? If so, is there any check to see 
that the submitted txt is consistent with the submitted xml?

	Thanks,
	Paul

---

From: Qin Wu <[email-masked]>
Date: Thu, 3 Nov 2016 01:26:19 +0000

-----邮件原件-----
发件人: WGChairs [mailto:[email-masked]] 代表 Paul Kyzivat
发送时间: 2016年11月3日 7:01
收件人: Robert Sparks; Joel M. Halpern; [email-masked]
主题: Re: document submission formats

On 11/2/16 4:12 PM, Robert Sparks wrote:
>>> submits differences it is either ignored or causes confusion. 
>>> Neither is to the benefit of the submitter.
>>
> For some time now, we have allowed people to submit _only_ the .xml 
> and the .txt is generated form the .xml.

Do we still allow both to be submitted? If so, is there any check to see that the submitted txt is consistent with the submitted xml?

[Qin]: Sure, I get used to submit both,always, the benefit is I can download xml as source file anywhere anytime at any device to make update. But I still will use diff tool to check generated txt based updated xml by comparing with original txt
I don't check whether submitted txt is consistent with xml, but I assume, we are not a malicious attacker, if we submit them inconsistently, we are ourselves victims.

	Thanks,
	Paul

>> Then he gets hit by a truck and I need to take over as editor. I 
>> would be inclined to start from the xml. It may take awhile to figure 
>> out what has happened and recover.
>>
>>> derived algorithmically from the XML.  And the XML will be 
>>> considered normative.
>>
>> markdown that then must be processed to generate the xml. That puts 
>> us in the same boat as with xml and txt today.
>>
>>     Thanks,
>>     Paul
>>
>>> Yours,
>>> Joel
>>>
>>>> arithmetically derived from a common source. My concern is that 
>>>> there is no guarantee that they are so related. (For instance, it 
>>>> wouldn't be hard for somebody to accidentally submit one form that 
>>>> was a version off from the others.)
>>>>
>>>> This is avoided if only one form is submitted, and the tools derive 
>>>> all the other formats. This still permits a variety of submission 
>>>> formats, so long as the tools relating them are controlled and 
>>>> invoked by the ietf.
>>>>
>>>>     Thanks,
>>>>     Paul
>>>>
>>>>> Just to make sure folks aren't talking past each other, there are 
>>>>> two suggestions being made.
>>>>>
>>>>> repository the way we allow .ps to be submitted now - in 
>>>>> _addition_ to the required .txt or .html). That shouldn't be hard 
>>>>> to add support for.
>>>>>
>>>>> Several others are suggesting allowing submission of only .md (the 
>>>>> way we have started accepting submission of only .xml recently). 
>>>>> That is the step Lee is pushing gently back against. It could be 
>>>>> made to happen, and I think it would be a reasonable long term 
>>>>> goal. I think we need to see some convergence in what the various 
>>>>> converters currently accept first.
>>>>> submission in that format satisfying the IPR/licensing 
>>>>> requirements as they are accepting just the xml.
>>>>>
>>>>> RjS
>>>>>
>>>>>
>>>>>>> <[email-masked] on behalf of 
>>>>>>> [email-masked]>
>>>>>>> wrote:
>>>>>>>
>>>>>>>>
>>>>>>> Somebody has to write and maintain tools to convert every input 
>>>>>>> format to every output format. I¹m a big fan of people creating 
>>>>>>> tools to parse whatever format(s) they happen to like, but I 
>>>>>>> don¹t want to assign work to the Tools Team, and ultimately 
>>>>>>> spending money on tool development.
>>>>>>> So, if
>>>>>>> anyone here is inclined to write a parser that will take their 
>>>>>>> favorite version of markdown (or auto detect various versions) 
>>>>>>> and convert it to canonical XML, I¹m sure you would have 
>>>>>>> community support (in the form of the beverage of your choice).
>>>>>>>
>>>>>>> Please read
>>>>>> If it is to automatically RFC text you are correct, but I don't 
>>>>>> think that is the purpose of it, I think of it more as a backstop 
>>>>>> archive method for the author team.
>>>>>> That being the case I am not entirely sure the tool needs to know 
>>>>>> anything much about the format.
>>>>>>
>>>>>> Stewart
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>
>>
>
>

---

From: Martin Thomson <[email-masked]>
Date: Thu, 3 Nov 2016 14:18:15 +1100

> that the submitted txt is consistent with the submitted xml?

I think that might be ameliorated with a minor UX change.

Show only one upload option and determine the type from the file
extension.  Provide a button that allows you to upload alternative
formats.

Then the default is that you only get one option.  It doesn't *fix*
the issue, but it makes it harder to mess up.

Looking forward to the .md option.  It's a shame that there are two
variants floating around in common use.

---

From: Daniel Migault <[email-masked]>
Date: Wed, 2 Nov 2016 23:38:14 -0400

Hi,

XML presents to me the following advanatge over markdown. It is more
stable, we have more experience with it, it is a convenient format for
document manipulation such as conversion to mobi format or checks. I would
tus recommend that whatever format is used for input there is an XML
version associated, either being submitted or generated from whatever fancy
format is preferred.

I think that is a good point to submit a single format whatever it is, this
format is convert to XML and checks apply from the XML version.

Regarding GitHub, I am wondering if we should not consider the IETF hosting
a git so all information remains in the hands of the IETF for
documentation.

Yours,

Daniel

On Wed, Nov 2, 2016 at 2:46 PM, Stewart Bryant <[email-masked]>
wrote:

> that we always submitted a complete human readable version so that it would
> be difficult for the submitter to deny that they were unaware of the IPR
> statement at the front of an ID,
>
> Stewart
>
>
>
>> Several others are suggesting allowing submission of only .md (the way we
>> have started accepting submission of only .xml recently). That is the step
>> Lee is pushing gently back against. It could be made to happen, and I think
>> it would be a reasonable long term goal. I think we need to see some
>> convergence in what the various converters currently accept first. The IESG
>> would need to make sure they were as comfortable with the submission in
>> that format satisfying the IPR/licensing requirements as they are accepting
>> just the xml.
>>
>> RjS
>>
>>

---

From: Tim Chown <[email-masked]>
Date: Thu, 3 Nov 2016 09:40:09 +0000

> On 2 Nov 2016, at 20:12, Robert Sparks <[email-masked]> wrote:
> 
>> *Today* .txt is still the authoritative format. AFAIK, if I submit both txt and xml then they are both archived, and trusted.
> For some time now, we have allowed people to submit _only_ the .xml and the .txt is generated form the .xml.

I had always assumed that the xml was the ‘master’, but then I use xml2rfc so am influenced by that.

Tim

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 03 Nov 2016 13:16:16 +0100

Hi Paul,

On 2016-11-03 00:01, Paul Kyzivat wrote:
> Do we still allow both to be submitted?

Yes.

> If so, is there any check to see 

Not currently.  We could put one in, though.  The hard part of that is
to decide what kind of diff fuzziness is acceptable.

I don't think it's really an error if the author has generated the text
with slightly out-of-date reference files, for instance; but that would
cause a diff.  The submission tool currently permits the date in the
text version to be up to 3 days in the past; a newly generated text file
would have today's date if the <date/> element was not fully filled in.

There may be other sources of small differences, and all of these have
to be accounted for, in order for the diff check to be of any use.
A broken diff check would cause a lot of annoyance ...

	Henrik

>>>>> there is
>>>>>>>> format to
>>>>>>>> favorite

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 3 Nov 2016 12:07:04 -0400

> folks prepare them using MS word.  So be it.

I don't care what authors do to create what they submit - I'm only 
concerned with what resides in the public repository for a particular 
draft version. The implication there is that all the things there are 
equivalent. So, as a reader of a draft I should be able to choose 
whichever one I find most convenient to read, and be confident that I am 
reading the same *content* as everybody else.

And this should extend to me deciding to reprocess the xml to generate 
some entirely different format to read.

If the different formats aren't assured of being equivalent then the 
assumption breaks down.

And here I am only talking about *drafts*. I realize that with RFCs this 
situation is different because it is mediated by the editors.

	Thanks,
	Paul

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 3 Nov 2016 12:10:52 -0400

> variants floating around in common use.

+1 to all above.

	Thanks,
	Paul

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 3 Nov 2016 12:14:38 -0400

> A broken diff check would cause a lot of annoyance ...

Yes, I agree that these points make it difficult to verify consistency. 
The best way to guarantee it is for the tool to do the generation.

Martin's proposal would ensure that. If there is an objection to hooking 
the formats to the file extension, then a single file selection plus 
radio buttons for the format would achieve the same end.

	Thanks,
	Paul