Subject: Note Well & GitHub

From: "Aaron Falk" <[email-masked]>
Date: Fri, 13 Jul 2018 14:16:06 -0400

I'm really late to the GitHub party so this may be a FAQ or otherwise 
dumb question but seeing things like [working group agendas posted on 
GitHub](https://datatracker.ietf.org/meeting/102/materials/agenda-102-iasa2-00) 
makes me wonder: Are comments or other content posted on GitHub covered 
by the IETF Note Well?  In other words, are they "IETF Contributions"?  
BCP78 makes the following definition:

>
> 	   a. "Contribution": any submission to the IETF intended by the
> 	      Contributor for publication as all or part of an Internet-Draft 
> or
> 	      RFC (except for RFC Editor Contributions described in Section 4
> 	      below) and any statement made within the context of an IETF
> 	      activity.  Such statements include oral statements in IETF
> 	      sessions as well as written and electronic communications, made 
> at
> 	      any time or place, that are addressed to:
>
> 	      o the IETF plenary session,
> 	      o any IETF working group or portion thereof,
> 	      o any Birds of a Feather (BOF) session,
> 	      o the IESG, or any member thereof on behalf of the IESG,
> 	      o the IAB, or any member thereof on behalf of the IAB,
> 	      o any IETF mailing list, including the IETF list itself, any
> 	        working group or design team list, or any other list 
> functioning
> 	        under IETF auspices,
> 	      o the RFC Editor or the Internet-Drafts function (except for 
> RFC
> 	        Editor Contributions, as described in Section 4 below).
>
> 	      Statements made outside of an IETF session, mailing list, or 
> other
> 	      function, that are clearly not intended to be input to an IETF
> 	      activity, group, or function are not IETF Contributions in the
> 	      context of this document.

As reasonable person might say that content on GitHub used to develop 
documents for an IETF working group is "within the context of an IETF 
activity".  I'm interested if that reasonable person would be correct.

--aaron

---

From: "Eggert, Lars" <[email-masked]>
Date: Fri, 13 Jul 2018 19:18:33 +0000

On 2018-7-13, at 20:16, Aaron Falk <[email-masked]> wrote:
> I'm really late to the GitHub party so this may be a FAQ or otherwise dumb question but seeing things like working group agendas posted on GitHub makes me wonder: Are comments or other content posted on GitHub covered by the IETF Note Well? In other words, are they "IETF Contributions"?

QUIC uses this, which is linked from the main README: https://github.com/quicwg/base-drafts/blob/master/CONTRIBUTING.md

Lars

---

From: "Eggert, Lars" <[email-masked]>
Date: Fri, 13 Jul 2018 19:21:27 +0000

> QUIC uses this, which is linked from the main README: https://github.com/quicwg/base-drafts/blob/master/CONTRIBUTING.md

I meant to add:

So yes, we are treating contributions on GitHub as contributions to the IETF process, and the Note Well applies.

I personally think any other approach would be fraught with peril.

Lars

---

From: "Aaron Falk" <[email-masked]>
Date: Fri, 13 Jul 2018 16:48:31 -0400

On 13 Jul 2018, at 15:21, Eggert, Lars wrote:

>>> I'm really late to the GitHub party so this may be a FAQ or 
>>> otherwise dumb question but seeing things like working group agendas 
>>> posted on GitHub makes me wonder: Are comments or other content 
>>> posted on GitHub covered by the IETF Note Well? In other words, are 
>>> they "IETF Contributions"?
>>
>> QUIC uses this, which is linked from the main README: 
>> https://github.com/quicwg/base-drafts/blob/master/CONTRIBUTING.md
>
> I meant to add:
>
> So yes, we are treating contributions on GitHub as contributions to 
> the IETF process, and the Note Well applies.
>

Ah, & now that I know what to look for I see that the IASA2 project has 
a similar page, although with a different name: 
https://github.com/IASA2/Background-Note-Well.  I wonder if there should 
be some conventions about such things?

--aaron

---

From: Nico Williams <[email-masked]>
Date: Fri, 13 Jul 2018 15:54:26 -0500

On Fri, Jul 13, 2018 at 04:48:31PM -0400, Aaron Falk wrote:
> Ah, & now that I know what to look for I see that the IASA2 project has a
> similar page, although with a different name:
> https://github.com/IASA2/Background-Note-Well.  I wonder if there should be
> some conventions about such things?

I think a single NOTE-WELL or NOTE-WELL.{md,txt} file with the NOTE WELL
content should suffice.  Any README should mention the IETF use and the
NOTE WELL.

Nico
--

---

From: "Aaron Falk" <[email-masked]>
Date: Fri, 13 Jul 2018 17:03:01 -0400

> content should suffice.  Any README should mention the IETF use and 

I agree that would seem quite sensible.  And again, I'm new to the 
GitHub but I'd be inclined to also add some mention of the IETF in the 
top level name so it's clear it's an IETF context.

--aaron

---

From: Nico Williams <[email-masked]>
Date: Fri, 13 Jul 2018 16:14:18 -0500

On Fri, Jul 13, 2018 at 05:03:01PM -0400, Aaron Falk wrote:
> >>Ah, & now that I know what to look for I see that the IASA2 project
> >>has a similar page, although with a different name:
> >>https://github.com/IASA2/Background-Note-Well.  I wonder if there
> >>should be some conventions about such things?
> >
> >I think a single NOTE-WELL or NOTE-WELL.{md,txt} file with the NOTE
> >WELL content should suffice.  Any README should mention the IETF use
> >and the NOTE WELL.
> 

A heavier-duty thing to do would be to have the IETF own a GitHub org
and hand out per-WG and per-individual-submission repos.  Then the IETF
could make sure that each of those repos have: a) README and NOTE-WELL
files, b) a LICENSE file, c) authorizations for the relevant WG chairs
and document editors/authors.

The IETF could also mirror these to other git repo hosting sites as a
backup.

Now, that would take some tooling and so will cost something, but
eventually I think we'll want that.

Nico
--

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 15 Jul 2018 03:23:41 +1200

1) There is a list for this: [email-masked]
2) There was an IESG statement early last year. I can't
find it on the web site, but I used it to write this:
https://github.com/becarpenter/animaproto/blob/master/CONTRIBUTING.md

Regards
   Brian

---

From: Martin Thomson <[email-masked]>
Date: Sun, 15 Jul 2018 08:41:43 -0400

> https://github.com/becarpenter/animaproto/blob/master/CONTRIBUTING.md

The same text is here:
https://github.com/martinthomson/i-d-template/blob/master/template/CONTRIBUTING.md

The important thing to note is that using a file with this name
ensures that notices are displayed in certain key places for
first-time contributors.  We might argue the relative effectiveness of
such measures, but I don't think that it's OK.

---

From: "Livingood, Jason" <[email-masked]>
Date: Mon, 16 Jul 2018 20:36:54 +0000

yes, we are treating contributions on GitHub as contributions to the IETF process, and the Note Well applies.

Ah, & now that I know what to look for I see that the IASA2 project has a similar page, although with a different name: https://github.com/IASA2/Background-Note-Well. I wonder if there should be some conventions about such things?

[JL] It’d be awesome if perhaps the tools team or someone created a sample starting GitHub project with the Note Well and anything else useful and then a WG could just clone that repository when they started up. I looked around quite a bit to see what other WGs were doing on GitHub before I created the IASA2 one and probably got a bunch of stuff wrong. For example, the WG does not expect to have many I-Ds but if we did I might create a drafts folder to contain them all, as I did with the Meetings folder. On the other hand there’s enough variation in WGs that we probably don’t want to over-specify things.

[JL] BTW, don’t get me started on taking something from GitHub to upload a draft on the IETF site. 😉 IMO that’s an area of friction for document authors that should/could be made much easier.

---

From: Martin Thomson <[email-masked]>
Date: Mon, 16 Jul 2018 16:56:29 -0400

On Mon, Jul 16, 2018 at 4:44 PM Livingood, Jason <
[email-masked]> wrote:

> [JL] It’d be awesome if perhaps the tools team or someone created a sample
> starting GitHub project with the Note Well and anything else useful and
> then a WG could just clone that repository when they started up. I looked
> around quite a bit to see what other WGs were doing on GitHub before I
> created the IASA2 one and probably got a bunch of stuff wrong. For example,
> the WG does not expect to have many I-Ds but if we did I might create a
> drafts folder to contain them all, as I did with the Meetings folder. On
> the other hand there’s enough variation in WGs that we probably don’t want
> to over-specify things.
>

You might be interested in https://github.com/martinthomson/i-d-template

[JL] BTW, don’t get me started on taking something from GitHub to upload a
> draft on the IETF site. 😉 IMO that’s an area of friction for document
> authors that should/could be made much easier.
>
The above includes a means of automating that process.

---

From: Lou Berger <[email-masked]>
Date: Mon, 16 Jul 2018 16:52:45 -0400

----------
On July 16, 2018 4:44:11 PM "Livingood, Jason" 

> On 2018-7-13, at 20:16, Aaron Falk <[email-masked]> wrote:
...
> then a WG could just clone that repository when they started up.

Fwiw here's the template I've been using for drafts I'm involved with - not 
saying it isn't a bit hacky, but it suffices for my needs...

https://github.com/louberger/xml-internet-draft-sample
Lou

...

---

From: "Livingood, Jason" <[email-masked]>
Date: Wed, 18 Jul 2018 18:53:45 +0000

Thanks – I noticed that and think it is useful. Even better IMO is a world where no special local software must be installed on my computer to take what is basically a text document and generate an XML file that can in turn be used to generate an I-D. Either a copy/paste into a form or one button to publish would be cool (and probably make it easier for new contributors).

Jason

From: Martin Thomson <[email-masked]>
Date: Monday, July 16, 2018 at 4:56 PM
To: "Livingood, Jason" <[email-masked]>
Cc: Aaron Falk <[email-masked]>, Lars Eggert <[email-masked]>, IETF discussion list <[email-masked]>
Subject: [EXTERNAL] Re: Note Well & GitHub

On Mon, Jul 16, 2018 at 4:44 PM Livingood, Jason <[email-masked]<mailto:[email-masked]>> wrote:

---

From: "Andrew G. Malis" <[email-masked]>
Date: Wed, 18 Jul 2018 16:33:36 -0400

Jason,

+1 to that, starting with Kramdown as the original source.

Cheers,
Andy

On Wed, Jul 18, 2018 at 2:53 PM, Livingood, Jason <
[email-masked]> wrote:

> Thanks – I noticed that and think it is useful. Even better IMO is a world
> where no special local software must be installed on my computer to take
> what is basically a text document and generate an XML file that can in turn
> be used to generate an I-D. Either a copy/paste into a form or one button
> to publish would be cool (and probably make it easier for new contributors).
>
>
>
> Jason
>
>
>
> *From: *Martin Thomson <[email-masked]>
> *Date: *Monday, July 16, 2018 at 4:56 PM
> *To: *"Livingood, Jason" <[email-masked]>
> *Cc: *Aaron Falk <[email-masked]>, Lars Eggert <[email-masked]>,
> IETF discussion list <[email-masked]>
> *Subject: *[EXTERNAL] Re: Note Well & GitHub
>
>
>

---

From: Alia Atlas <[email-masked]>
Date: Wed, 18 Jul 2018 17:21:41 -0400

There is http://xml2rfc.tools.ietf.org/experimental.html#kramdown for a
method to go from
Kramdown to xml.  No need to install any software.

Regards,
Alia

On Wed, Jul 18, 2018 at 4:34 PM Andrew G. Malis <[email-masked]> wrote:

>> Thanks – I noticed that and think it is useful. Even better IMO is a
>> world where no special local software must be installed on my computer to
>> take what is basically a text document and generate an XML file that can in
>> turn be used to generate an I-D. Either a copy/paste into a form or one
>> button to publish would be cool (and probably make it easier for new
>> contributors).
>>
>>
>>
>> Jason
>>
>>
>>
>> [JL] It’d be awesome if perhaps the tools team or someone created a
>> sample starting GitHub project with the Note Well and anything else useful
>> and then a WG could just clone that repository when they started up. I
>> looked around quite a bit to see what other WGs were doing on GitHub before
>> I created the IASA2 one and probably got a bunch of stuff wrong. For
>> example, the WG does not expect to have many I-Ds but if we did I might
>> create a drafts folder to contain them all, as I did with the Meetings
>> folder. On the other hand there’s enough variation in WGs that we probably
>> don’t want to over-specify things.
>>
>>
>>
>> <https://github..com/martinthomson/i-d-template>
>>
>>
>>
>> [JL] BTW, don’t get me started on taking something from GitHub to upload
>> a draft on the IETF site. 😉 IMO that’s an area of friction for document

---

From: "Andrew G. Malis" <[email-masked]>
Date: Wed, 18 Jul 2018 18:02:46 -0400

Alia,

The request is to go from Kramdown to text in one step, no intermediate xml
files required.

Cheers,
Andy

On Wed, Jul 18, 2018 at 5:21 PM, Alia Atlas <[email-masked]> wrote:

>>> a draft on the IETF site. 😉 IMO that’s an area of friction for
>>> document authors that should/could be made much easier.
>>>

---

From: Michael Richardson <[email-masked]>
Date: Fri, 20 Jul 2018 16:29:10 -0400

Andrew G. Malis <[email-masked]> wrote:
    > The request is to go from Kramdown to text in one step, no
    > intermediate xml files required.

But, the XML is now the canonical form, so we really want that.

-- 
]               Never tell me the odds!                 | ipv6 mesh networks [ 
]   Michael Richardson, Sandelman Software Works        | network architect  [ 
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: Nico Williams <[email-masked]>
Date: Fri, 20 Jul 2018 16:06:12 -0500

> But, the XML is now the canonical form, so we really want that.

+1.

I don't mind (and even have authored[0]) tools that convert from some other
format to XML, but I very much mind not having XML as the canonical
form.  Even if there is/were a better format to choose as the canaonical
one, at this point the cost of switching woul dbe too high, so let's not
even go there.

Nico

[0] lyx2rfc.

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Sat, 21 Jul 2018 13:39:55 -0400

My tools will go from Markdown, Word or XML to any of the input formats
plus HTML and TXT.

They are available on Github and run on Windows, OSX and Linux but you do
have to install dotnet Core.

I will try to get round to packaging them up and maybe putting up a server.