Subject: [netmod] yang-03, import/include by-revision

From: Andy Bierman <[email-masked]>
Date: Sat, 31 Jan 2009 10:55:37 -0800

Hi,

This section on File Format is a normative section:

5.2.  File Layout

    YANG modules and submodules are typically stored in files, one module
    or submodule per file, with the name of the file on the form:

      module-or-submodule-name ['.' revision-number] ( '.yang' / '.yin' )

    YANG compilers can find imported modules and included submodules via
    this convention.  While the YANG language defines modules, tools may
    compile submodules independently for performance and manageability
    reasons.  Many errors and warnings that cannot be detected during
    submodule compilation may be delayed until the submodules are linked
    into a cohesive module.

Issue 1)  A normative deterministic mechanism within YANG file
           to determine revision is needed (already brought up on list).

Issue 2)  YANG compilers 'can' find... ?
           This needs to be MUST/SHOULD/MAY language.

Issue 3)  The '.' char is allowed in module-or-submodule-name,
           so it should not be used as a separator in this file format.
           Some operating systems may not like multiple '.' chars
           in the filename either. Maybe underscore '_' would be better.

Issue 4) There is no field anywhere in YANG called 'revision-number'.
          This should be called 'revision-date'.

Issue 5) The revision is optional in the file format, so I am not
          sure what value it has at all.  Does that mean there
          is no revision, or does it mean the user just felt
          like leaving it out?

Issue 6) The file format suggests that '.tin' files are input files,
          but they are only defined as output files in the draft.
          (Let's leave it that way.)  I prefer to have 1 input format.
           YANG modules are store in YANG files, which SHOULD (MAY?) be
           named with the '.yang' extension.

    import-stmt            = import-keyword sep identifier-arg-str optsep
                          "{" stmtsep
                              prefix-stmt stmtsep
                              [revision-stmt stmtsep]
                          "}"

Issue 7) Why is the full revision-stmt needed in the import-stmt
          and include-stmt?  If the description-stmt is really so
          important here (IMO no) then it should be a sub-statement
          of 'import' or 'include' directly, not a sub-stmt of 'revision'.
          I prefer this ABNF instead (without a description-stmt):

      import-stmt            = import-keyword sep identifier-arg-str optsep
                          "{" stmtsep
                              prefix-stmt stmtsep
                              [revision-keyword sep date-arg-str stmtsep]
                          "}"

    Sec 7.1.5, para 3:

    When the optional "revision" is present, any typedef, grouping,
    extension, feature, and identity referenced by definitions in the
    local module are taken from the specified revision of the imported
    module.

Issue 8:
    The phrase 'specified revision' needs clarification:
    - exact match of the highest value date-arg-str in a
      revision-stmt in the imported module (or included submodule)
    - missing revision SHOULD select the most recent, if the
      imported module (or included submodule) has revision-stmt(s)
    - missing revision MAY select any revision, if the
      imported module (or included submodule) does not have any
      revision-stmts

Andy

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

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 31 Jan 2009 21:05:12 +0100 (CET)

>            to determine revision is needed (already brought up on list).

Ok.

>            This needs to be MUST/SHOULD/MAY language.

I suggest SHOULD.

>            in the filename either. Maybe underscore '_' would be better.

And some OSs use 8+3 filenames.  I suggest changing the first '.' to '_'.

>           This should be called 'revision-date'.

Ok.

>           is no revision, or does it mean the user just felt

Both, but maybe we should be more restrictive, i.e. say that if the
module has a revision stmt, then the filename SHOULD include the
latest revision date?

>           (Let's leave it that way.) 

That was never the intention.  Some users (I know one in this WG) will
write YIN natively.  This is perfectly legal.   Your ietf guidelines
draft should probably require the YANG format though.

>                               [revision-keyword sep date-arg-str stmtsep]

I agree.  This was a bug.

>       imported module (or included submodule) does not have any

Ok.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 31 Jan 2009 12:20:32 -0800

Martin Bjorklund wrote:
>>]

all OK but 4 and 5 (inline)

>>           This should be called 'revision-date'.

there is no revision-date either in the ABNF,
so I suggest creating a definition somewhere:

    revision-date = date-arg-str

The text about revision-stmt, highest-valued instance,
etc. is needed here.

> module has a revision stmt, then the filename SHOULD include the

case 1)

   import A { prefix a; revision X; }

   - if A has no revision X, then the import MUST fail
     (no module used for A)
   - A is considered 'revision X' if and only if its highest valued
     revision-date is X.
   - A has no revision if it has no revision-stmts.
     Any import of A requresting a specific version MUST fail

case 2)

   import A ( prefix a; }

   - if A has revision-stmts (in each instance)
     then the instance with the highest valued revision-date
     SHOULD be used

   - if A does not have revision-stmts (in each instance)
     then it is implementation-specific which instance
     of module A is used

Andy

---

From: WashamFan <[email-masked]>
Date: Sun, 01 Feb 2009 10:49:21 +0800

Hi, 
>     - A is considered 'revision X' if and only if its highest valued

I got a little confused. X is nonsense if it does not equal highest valued revision-date, i.e, we should always import the most recent module. So Why should we need 'revision X' in the statement?

washam

---

From: Andy Bierman <[email-masked]>
Date: Sat, 31 Jan 2009 22:25:26 -0800

> I got a little confused. X is nonsense if it does not equal highest valued revision-date, i.e, we should always import the most recent module. So Why should we need 'revision X' in the statement?

no.

as modules get updated over time, it is important to
preserve pre-existing modules.  Consider a module A that
imports a grouping from module B.  The contents of A
do not change over time even if the grouping in B
does change over time.  Import-by-revision allows
module A to 'freeze' its version of the grouping,
even if other modules import newer versions of B,
and the grouping has different contents in those
other modules.

Andy