Subject: [netmod] [Fwd: I-D Action:draft-ietf-netmod-yang-usage-01.txt]

From: Andy Bierman <[email-masked]>
Date: Wed, 12 Aug 2009 20:31:09 -0700

Hi,

FYI: new YANG guidelines draft

There are still some [TBD] details scattered about
that need to be resolved.  I will try to do that
in the next month.  All the mailing list issues are settled.

I added ietf-template.yang, which is just a shell
that YANG authors can fill in with a data model.
I figured that this is not a YANG tutorial, so
the expresso-machine.yang module can wait for another
draft.

Please review ASAP and let me know if there are any problems,
bugs, missing guidelines, etc.

thanks,
Andy

Subject: [netmod] I-D Action:draft-ietf-netmod-yang-usage-01.txt
From: [email-masked]
To: [email-masked]
Cc: [email-masked]
Date: Wed, 12 Aug 2009 14:30:01 -0700 (PDT)
List-Id: NETMOD WG list <netmod.ietf.org>

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the NETCONF Data Modeling Language Working Group of the IETF.

	Title           : Guidelines for Authors and Reviewers of YANG Data Model Documents
	Author(s)       : A. Bierman
	Filename        : draft-ietf-netmod-yang-usage-01.txt
	Pages           : 28
	Date            : 2009-08-12

This memo provides guidelines for authors and reviewers of standards
track specifications containing YANG data model modules.  Applicable
portions may be used as a basis for reviews of other YANG data model
documents.  Recommendations and procedures are defined, which are
intended to increase interoperability and usability of NETCONF
implementations which utilize YANG data model modules.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-netmod-yang-usage-01.txt

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

Below is the data which will enable a MIME compliant mail reader
implementation to automatically retrieve the ASCII version of the
Internet-Draft.
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 13 Aug 2009 08:12:19 +0200

> bugs, missing guidelines, etc.

If we use a reference statement to identify the RFC, should this
statement then not be part of the revision statement, that is:

revision 2009-08-12 {
  description "Initial revision";
  reference "RFC XXXX";
}

Right now, you have the reference statement where all the meta data is
and it seems YANG does not even allow to place the reference statement
like I propose here. But common usage has been to refer to the RFC in
the revision statement equivalent in the SMIv2 world.

I am not sure I really see the value of requiring the file name for
unpublished documents in the comments. The more places an author has
to maintain with each revision, the more errors can be made. We
already have the DRAFT-XX in the URN and in the SMIv2 world, we
managed to survive without such a comment.

/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: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 13 Aug 2009 08:52:58 +0200

> the revision statement equivalent in the SMIv2 world.

The example should actually be:

  revision 2009-08-13 {
    description
     "Initial revision.";
    reference
     "RFC XXXX: Common YANG Data Types";
  }
  // RFC Ed.: replace XXXX with actual RFC number and remove this note

I added the title of the RFC (as I normally do) since not everybody
memorizes all the RFC numbers. Martin, can we change YANG to allow
this?

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 13 Aug 2009 08:59:07 +0200 (CEST)

> memorizes all the RFC numbers. Martin, can we change YANG to allow

Yes I think we should.  In fact, we can view this as a bug - in all
other places where a 'description' statement is allowed, 'reference'
is also allowed.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 13 Aug 2009 02:47:47 -0700

> other places where a 'description' statement is allowed, 'reference'

I disagree.
It is not a bug -- it is feature-creep.
We can use a comment for this purpose.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 13 Aug 2009 12:03:35 +0200

> We can use a comment for this purpose.

I like the bug fix.

/js