Re: [Teas-ns-dt] Tools to compile the framework draft

["Dongjie (Jimmy)" <[e-mail]>]

[CC the authors of VPN+ framework]

Hi Eric,

My assumption is the deign team framework would reuse or reference existing work when they are useful to avoid duplication and waste of energy. Based on the design team’s discussion, there is consensus that VPN+ framework provide useful text in several sections, some of which are directly used after small modifications, and some sections are referenced to help to provide a complete framework.

Quoting from the meeting minutes of January 23:

“There was discussion of how author lists and editorship will be aligned. Jari responded that first off, we need to be very clear about source of things, if text or effort from elsewhere is used, that needs to result in acknowledgements or author list entries. Secondly, the design team should have its own editor(s) as a synchronization point and we should not expand the list of editors too far.”

Based on this, my request is simple: according to the amount of text reused from VPN+ framework, this needs to be reflected in the author list, if the authors of VPN+ are willing to participate in the design team work.

Best regards,
Jie

From: Eric Gray [mailto:[e-mail]]
Sent: Thursday, February 6, 2020 5:24 AM
To: Dongjie (Jimmy) <[e-mail]>om>; Eric Gray <eric.gray=[e-mail]>rg>; Jari Arkko <jari.arkko=[e-mail]>rg>; [e-mail]; John E Drake <[e-mail]>
Subject: RE: Tools to compile the framework draft

Jie,

              I think you are either making assumptions that are not common among the design team members, or you are working with a misunderstanding of the intent of the framework draft.

              There is no intention for there to be an alignment between this draft and the enhanced VPN draft.

              The intent is to avoid conflict or misalignment with that work – to the extent possible and compatible with the rough consensus of this (possibly over-large) design team for a transport (network) slicing framework – and to refer to the enhanced VPN draft as an example of related work.

              This is a (perhaps) subtle but not insignificant difference.

              To the extent possible, ongoing work in this framework draft must be orthogonal to the ongoing work in the enhanced VPN.

              See additional comments – that try to clarify this – below.

From: Teas-ns-dt <[e-mail]<mailto:[e-mail]>> On Behalf Of Dongjie (Jimmy)
Sent: Wednesday, February 5, 2020 10:25 AM
To: Eric Gray <eric.gray=[e-mail]<mailto:eric.gray=[e-mail]>>; Jari Arkko <jari.arkko=[e-mail]<mailto:jari.arkko=[e-mail]>>; [e-mail]<mailto:[e-mail]>; John E Drake <[e-mail]<mailto:[e-mail]>>
Subject: Re: [Teas-ns-dt] Tools to compile the framework draft

Hi Eric,

Please see my replies inline:


From: Teas-ns-dt [mailto:[e-mail]] On Behalf Of Eric Gray
Sent: Wednesday, February 5, 2020 9:40 PM
To: Dongjie (Jimmy) <[e-mail]<mailto:[e-mail]>>; Jari Arkko <jari.arkko=[e-mail]<mailto:jari.arkko=[e-mail]>>; [e-mail]<mailto:[e-mail]>; John E Drake <[e-mail]<mailto:[e-mail]>>
Subject: Re: [Teas-ns-dt] Tools to compile the framework draft

Jie,

              As I recall, this was suggested (I believe, by you) at one of the design team meetings.

              Jari had answered this suggestion by stating that we should keep the list of “Authors” to a minimum and based on direct contributions to this draft (as opposed to text “lifted” from other drafts and RFCs).

[Jie] On that conference call, I volunteered to be one of the editors of the design team framework to help the alignment with the VPN+ framework. Jari said he wanted to keep the list of editors small, and I was OK with that. What I’m suggesting now is to be added as coauthor, based on the contribution to this draft.

I’m not sure what you mean by “direct contribution”, to my understanding, the contribution in IETF is evaluated by the text being provided and accepted.

Providing text requires more than simply pointing to text.  Several people argued that we should re-use text related to (transport) network slicing from the enhanced VPN (or VPN+) draft.  This is not a contribution of text any more than “that’s not correct” is a valid (or complete) comment about existing text.

At a meeting a few Thursdays ago, John expressed frustration that people had apparently not read the VPN+ draft or it would be obvious that a lot of text from that draft should be used in this framework draft (and – in fact – in a lot of what we are doing in this design team).

I pointed out that telling everyone to “go off and read X draft” – even for as essential a reason as to see the shape of the wheel already invented – is hardly an approach that allows for work in parallel.  Having everyone do everything, step by step, is not an efficient way to divide a problem into discrete pieces that can be addressed in parallel.

So, John offered to annotate the skeleton provided by Jari with specific text to be added from the VPN+ draft.  He did so, and asked me to further annotate his annotations.  I did so, and presented the results on the following Monday (John was unable to attend that day).

John’s proposal – especially as expanded on and annotated by myself – was a “direct contribution.”

I then created a branch in GitHub and made the text additions we had proposed and presented.  Jari merged these changes prior to the next (Thursday) meeting.

Jari’s earlier providing of a framework “skeleton” in GitHub, was obviously a “direct contribution.”

              In particular, there is a need to leave room for other authors and contributors to be listed.

[Jie] Then what is the criteria of adding other authors or contributors? I guess it would also base on the text contribution they make.

The answer to this is essentially a brief tutorial on the “inner workings” of the Internet Draft process.

There is an upper limit on how many people can be listed on the front page and this has led to the need to provide “graduated authorship” for developing Internet Drafts – i.e. – “Authors”, “Editors and Contributors”, (possibly) “Authors and Contributors”, and (sometimes) “Editors, Authors and Contributors.”

Because of the size of the current design team, we will very likely end up with “Editors” and “Contributors.”  Because the distinction between an “author” and a “contributor” is a somewhat arbitrary one, we should probably stick with “contributors”, unless and until the level of “contribution” rises to the point where the contributor should be acknowledged as an “author.”

What level this occurs at is a judgement call.  And it is easier to add people to any list than it is to take them away.

As a sort of reference, I am pretty sure all of us have seen somewhat lengthy trade journal publications with one or more editors and a list of contributors, where each “contribution” may be a reasonably lengthy paper that could have been published on its own.

See above for what constitutes a text contribution.

              Before we are done, we will obviously need to ensure that we have properly attributed all sources of text (I anticipate adding a paragraph – along with the usual “thanks for reviewing” paragraph – to the ACK section), but being an author of a draft/RFC used as a source for a subsequent draft/RFC has never been justification for being explicitly listed as an author or contributor in the latter draft/RFC.  Otherwise, the list of “Authors” in any present-day draft would be very lengthy.  We simply state that (some subset of the) text was taken from the earlier work.

[Jie] Please note the coauthors of VPN+ framework draft are also participating in the on-going development of the design team framework, and if you remember I’ve been suggesting to reuse the VPN+ framework from the beginning of our framework discussion. The above case you mentioned usually applies when an earlier work is reused and the original authors no longer participate in the new work.

Actually, it applies generally, unless the original authors have taken the extra steps of tailoring their earlier work to fit.  That work was done by John and myself.

Remember that every (active) participant in the design team is considered a contributor and hopefully you will also remember that several people recommended re-using text from the VPN+ draft.

              Note that this applies generally to any text deliberately used from any earlier work.  There may be small sets of words or phrases that have been unintentionally re-used, or are required either as part of the template or RFC Editor ID requirements, that will most likely not be attributed.

              All of these considerations are – in part – why there is the IETF “Note Well.”

              The “direct” contribution in this case was from John Drake, who provided a guide to how to re-use the text from the enhanced VPN draft to fill in the skeletal draft provided by Jari.

[Jie] I really appreciate the support and guide from John on the reuse of VPN+ framework, while as I mentioned the major contribution in IETF is the text.

The text that John and I contributed, not the text that already existed in the VPN+ draft – which needed alteration to fit.

              As Jari also stated, all participants in the weekly meetings – or on the mailing list – are contributors to this work.  This is justified, because there is an opportunity for those participants to comment on the drafts in progress.  The same is true for the definitions draft.

              By the way, I am evaluating comments from at least two people (Xufeng and yourself) that were made on the mailing list for potential impact on the framework draft.  Unfortunately, I am a little busy right at the moment.  😊

[Jie] Looking forward to your feedback on the comments.

Still working on that.  Among other things…

Best regards,
Jie

--
Eric

From: Dongjie (Jimmy) <[e-mail]<mailto:[e-mail]>>
Sent: Tuesday, February 4, 2020 9:46 PM
To: Jari Arkko <jari.arkko=[e-mail]<mailto:jari.arkko=[e-mail]>>; [e-mail]<mailto:[e-mail]>; John E Drake <[e-mail]<mailto:[e-mail]>>; Eric Gray <[e-mail]<mailto:[e-mail]>>
Subject: RE: Tools to compile the framework draft
Importance: High

Hi Jari,

Thanks for your effort on this.

I checked the current version of the framework draft, many text of VPN+ framework draft is reused in the introduction, framework and security considerations sections, this is good for the alignment between the two drafts. Then it would be reasonable to add the author of VPN+ framework draft also to the author list of this document. Thanks.

Best regards,
Jie

From: Teas-ns-dt [mailto:[e-mail]] On Behalf Of Jari Arkko
Sent: Tuesday, February 4, 2020 5:33 AM
To: [e-mail]<mailto:[e-mail]>; John E Drake <[e-mail]<mailto:[e-mail]>>; Eric Gray <[e-mail]<mailto:[e-mail]>>
Subject: [Teas-ns-dt] Tools to compile the framework draft

I’ve finally managed to set up the framework draft compilation correctly. Struggled with some newer versions of tools. But the one I recommend and the associated makefiles work.

See the readme at https://github.com/teas-wg/teas-ns-dt/tree/master/framework<https://protect2.fireeye.com/v1/url?k=dbce027c-8747d86c-dbce42e7-0cc47ad93e2a-2b5fc923eca7e3c9&q=1&e=2f9bbdce-061b-46f3-87c3-307970015ce1&u=https%3A%2F%2Fgithub.com%2Fteas-wg%2Fteas-ns-dt%2Ftree%2Fmaster%2Fframework> for instructions; you’ll need to install make, kramdown-rfc2629, and xml2rfc but there are instructions. Then type make and the system compiles the .md to .txt automatically.

Jari