Subject: [netmod] <CODE BEGINS> convention

From: Andy Bierman <[email-masked]>
Date: Wed, 02 Dec 2009 11:33:49 -0800

Hi,

I noticed this change in yang-types-05:

       <CODE BEGINS> file "ietf-yang-types.yang"

     module ietf-yang-types {

The problem with this variant is that there should be nothing
but 'extra' whitespace added to the 'CODE'.  For legal reasons,
and for consistency for tools that process <CODE BEGINS>
generically in any I-D or RFC, the file "filename" stuff
needs to be removed.

Besides, the file is really ietf-yang-types.2009-11-10.yang,
according to the YANG spec, which also does this:

  <CODE BEGINS> file "yang.abnf"

If every WG decides to add different extra text to the
normative text tagged as 'CODE', then we will have a
mess before long.

I suggest getting the generic <CODE BEGINS> changed so
standard meta-data can be added, such as 'file':

  <CODE BEGINS file="ietf-yang-types.yang">

This makes it more XML-ish, and from a legal POV,
makes it clear what characters constitute 'CODE',
and which do not.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 2 Dec 2009 14:27:57 -0500

>generically in any I-D or RFC, the file "filename" stuff

Okay, I'm not a lawyer.  Please explain how lawyers will
get involved if you use the "<CODE BEGINS>" in this way.

>makes it clear what characters constitute 'CODE',

I would avoid the "XML attribute"-like way since this
tag is definitely _not_ XML.  We should help anyone
to think that this is XML.  IMHO we should not be using
chevrons at all, but maybe this is a "legal issue" also.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 02 Dec 2009 12:47:41 -0800

> get involved if you use the "<CODE BEGINS>" in this way.

Read the IETF TLP.
It says everything between <CODE BEGINS> and <CODE ENDS> is code.
The extra stuff (file "name") is not part of the YANG language.
It is not code.  It needs to be removed.

The IETF does not need to standardize the file names
used by some tool or person saving RFC fragments to
external storage.  The file name is not mentioned
anywhere in the document.  Is it important?  Is it
normative?  Why is it even there?

> chevrons at all, but maybe this is a "legal issue" also.

Fine.  Then just <CODE BEGIN> should be used,
as specified in the TLP.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 2 Dec 2009 15:45:21 -0500

>It is not code.  It needs to be removed.

To the IETF, this means only that text appearing between the <CB>
and <CE> is a "code component" and the IETF "grants to each person
who wishes to exercise such rights", etc etc.

I'm sure we will happily give these rights to the string at the end
of the <CB> line.  I don't see lawyers getting involved in this.

Thanks,
 Phil

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 3 Dec 2009 00:28:39 +0100

> Read the IETF TLP.

I did.

> It is not code.  It needs to be removed.

OK, lets read it together. Here is the text from the FAQ
<trustee.ietf.org/docs/IETF-Copyright-FAQ.pdf>:

 3.2 Must I do anything special if I include code in my IETF Contribution? 

   If you include code in an IETF Contribution, you are encouraged to
   label it with markers such as <CODE BEGINS> and <CODE ENDS>, though
   these markers are not strictly required.  Rather, any types of
   common code components included in IETF Contributions and listed at
   http://trustee.ietf.org/policyandprocedures.html are automatically
   treated as ?Code Components? for purposes of the TLP.

And here is the relevant quote from the IETF Trust Legal Provisions
Relating to IETF Documents Effective Date: September 12, 2009:

4. License to Code Components.   

 a. Definition.  IETF Contributions and IETF Documents often include
    components intended to be directly processed by a computer (?Code
    Components?).  A list of common Code Components can be found at
    http://trustee.ietf.org/license-info/.

 b. Identification.  Text in IETF Contributions and IETF Documents of
    the types identified in Section 4.a above shall constitute ?Code
    Components?.  In addition, any text found between the markers
    <CODE BEGINS> and <CODE ENDS>, or otherwise clearly labeled as a
    Code Component, shall be considered a ?Code Component?.

Both, YANG and ABNF are listed in http://trustee.ietf.org/license-info/.
According to my reading of the IETF TLP and its FAQ, we do not even
need <CODE BEGINS> and <CODE ENDS> markers to have the YANG modules
and ABNF covered by an appropriate license.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Wed, 02 Dec 2009 15:46:05 -0800

> and ABNF covered by an appropriate license.

We don't need (file "filename") either.  What's your point?

As long as every YANG author gets to choose what to
put in their draft, that's fine.  Others may choose
to follow the IETF guidelines, even if they are
not strictly mandatory.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 3 Dec 2009 01:01:59 +0100

> We don't need (file "filename") either.  What's your point?

The file name is practically useful for automatically extracting a
code component and putting it into a sensible file. This probably
makes it a bad idea since there are ways of doing this manually.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 03 Dec 2009 10:47:03 +0100

> chevrons at all, but maybe this is a "legal issue" also.

IETF Trust Legal Provisions say that '..., any text found between the
markers <CODE BEGINS> and <CODE ENDS>, or otherwise clearly labeled as a
Code Component, shall be considered a "Code Component"'. So even the
chevrons are not strictly required. In any case, it is IMO irrelevant
whether the file name is considered part of the code component or not.

Lada

> 
> Thanks,
>  Phil
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: David Partain <[email-masked]>
Date: Thu, 3 Dec 2009 16:45:35 +0100

Hi,

I don't see that the text implies we can't put stuff in that is helpful (as I 
think this is).  I think the filenames are useful.

David

---

From: David Partain <[email-masked]>
Date: Thu, 3 Dec 2009 16:49:40 +0100

> makes it a bad idea since there are ways of doing this manually.

At the risk of being overly zealous and repetitive, I would like to keep it.  
Having watched the mess of the filenames for SNMP MIBs, I really really think 
this is a good idea.

David

---

From: Andy Bierman <[email-masked]>
Date: Fri, 04 Dec 2009 02:16:30 -0800

> Having watched the mess of the filenames for SNMP MIBs, I really really think 

I would like to know why the file naming conventions
defined in yang-09, sec 5.2 are being ignored by
this undocumented and undefined CODE BEGINS convention.
I find it harmful to see drafts with examples that don't even
follow the established guidelines.  People will copy
this wrong way of naming YANG files.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 4 Dec 2009 12:10:20 +0100

> this wrong way of naming YANG files.

Thanks for pointing out the inconsistency. I agree that we have to fix
the file names to follow the YANG specs. I note, however, that the
square brackets likely indicate that the [ '.' revision-data ] part is
optional and there is no text in 5.2 explaining this further, that is
there is no text saying that this part must be present if there is a
revision statement (in case that was the intention). Anyway, I agree
that we should get this right and include revision-date in the file
names.

(Personally, I am still not happy with the choice of the '.' as a
 separator but that is a separate issue. I have to read the list
 discussion about this again.)

/js

---

From: Andy Bierman <[email-masked]>
Date: Fri, 04 Dec 2009 08:00:36 -0800

> that we should get this right and include revision-date in the file

I went looking for the '-' vs. '.' thread and found other
emails that reminded me that the optional usage of revisions
is still a concern to me.

>>>>**** THE FOLLOWING IS A WGLC COMMENT ****<<<<<

It does not make any sense to talk about different versions
of a YANG [sub]module without a new revision date.  There is no way
to even distinguish which is the old version and which is
the new version in a standard way.

Sec 10:

  For any published change, a new "revision" statement (Section 7.1.9)
  SHOULD be included in front of the existing revision statements.

Edit 1:  s/SHOULD/MUST

Edit 2:  state (somewhere in sec. 10) that a module without
         revisions MUST NOT change (ever)

Either that, or add text that explains how the standard is
used to distinguish different versions of a conceptual
YANG [sub]module, by some means other than the revision date.

>  discussion about this again.)

I thought you were the one who objected to '-' and
wanted it changed to '.'.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 4 Dec 2009 19:16:19 +0100

On Fri, Dec 04, 2009 at 05:00:36PM +0100, Andy Bierman wrote:

: I thought you were the one who objected to '-' and
: wanted it changed to '.'.

I think we should avoid characters that are frequently used for other
purposes. The '.' is conventionally used to separate the file type
suffix from a file name. The '-' is frequently used in module names.
Hence, I would avoid both of them. I would prefer to use say '_' as
used by the Debian package names. If we want to be absolutely safe of
conflicts, we would pick a separator that is not allowed to appear in
a module name.

/js

---

From: Andy Bierman <[email-masked]>
Date: Fri, 04 Dec 2009 12:18:13 -0800

> conflicts, we would pick a separator that is not allowed to appear in

yep -- I begged the WG (early on) to reserve 1 printable
character from identifiers, but people insisted they need
the freedom to use every legal XML identifier value.

When I read sec. 5.2, I wonder:
If foo and foo.2009-01-01 are both legal
module names, then how do I know for sure
which form of the filename is really present?
And if these are both legal module names, then what
happens if there is a version of the 'foo' module
released on 2009-01-01?

Baked-in fragility is not a good idea.
Engineers usually try to avoid such fragile SW design.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 4 Dec 2009 21:22:04 +0100

> the freedom to use every legal XML identifier value.

My keyboard still has characters left that are not allowed in a legal
YANG identifier - so I do not see this as a hard engineering challenge.

/js

---

From: Andy Bierman <[email-masked]>
Date: Fri, 04 Dec 2009 12:26:38 -0800

> YANG identifier - so I do not see this as a hard engineering challenge.

Really?
So which characters are available that are
present on every keyboard, and are not special
characters in any operating system filespec?

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 4 Dec 2009 21:33:55 +0100

> characters in any operating system filespec?

I assume every keyboard has a '+' for example. And I was not talking
about "any operating system filespec". I was talking about (a) picking
a character that is not a legal module name character and (b) avoiding
the '.' since it is used by major OSes as a separator for the file
type suffix. I am not insisting on '+', perhaps '@' could also work or
'%' or ... I have quite a few such keys left on my keyboard.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sat, 05 Dec 2009 09:50:59 -0800

> '%' or ... I have quite a few such keys left on my keyboard.

After a few minutes playing around with bash,
it seems either '+' or '@' will work on linux,
although @ will be escaped wrt/ tab completion.
But '+' is special in printf formatting and
regular expressions.

I would support changing the field separator
to '@' instead of '.', unless it breaks common
tools somehow.

Andy