Subject: Re: [netmod] Proposed consensus mail on yang-00000: module update rules

From: Martin Bjorklund <[email-masked]>
Date: Sun, 02 Nov 2008 23:40:44 +0100 (CET)

Balazs Lengyel <[email-masked]> wrote:
> 
> 
> Martin Bjorklund wrote:
> > A definition may be revised in any of the following ways:
> > - New data definition statements may be added if they do not add
> >   mandatory nodes (^mandatory-nodes^) to existing nodes, or if they
> >   are conditionally dependent on a new feature (i.e. have a
> >   "if-feature" statement which refers to a new feature).
> BALAZS: So a new mandatory leaf at the root level is allowed? I think it must
> not. That is a clear incompatible change will brake old managers.

No, it should not be allowed.  I will fix this.

/martin

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

---

From: "Ersue, Mehmet (NSN - DE/Munich)" <[email-masked]>
Date: Thu, 6 Nov 2008 16:42:37 +0100

I support the proposal from the interim meeting which has been 
updated with a text paragraph by Martin. 

I think it is useful that the revision of the module must be advertised 
as well, as stated in the YANG-02 document. This allows a manager 
to find out what exactly is supported by a particular agent.

I am in favor of the text Martin wrote on change rules. In general, 
it is a good idea to list what is allowed. It is not necessary to 
state explicitly what is not allowed. 

I also like the two design goals and support them in the document:
>   - Protect old clients
>     We want a client that uses version x of a module to be able to
>     function when talking to a server implementing version x+1.
> 
>   - Protect importers
>     A new published module version must not break existing other
>     modules that imports from the module.

Mehmet 
(on behalf of Bernd Linowski)

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]] On Behalf Of ext David Partain
> Sent: Tuesday, October 28, 2008 4:03 PM
> To: [email-masked]
> Subject: [netmod] Proposed consensus mail on yang-00000: 
> module update rules
> 
> Greetings,
> 
> This is a call for consensus about issue 'yang-00000: module
> update rules'.  See the wiki at
> http://wiki.tools.ietf.org/wg/netmod/trac/wiki/Issues_yang#issue-00000
> 
> PLEASE speak up if you favor or object to the proposed rules,
> including people who attended the interim.  Silence is impossible
> to interpret.
> 
> Issue: Need to define the rules for how modules are updated (new
> revisions published).
> 
> The first day of the interim meeting spent a great deal of time
> talking about this issue.  This mail does not give a blow-by-blow
> recounting of the discussion but rather tries to summarize what
> was discussed and the conclusions.
> 
> The general principle is that when updating a module without name
> changes, the module may become less constrained, but never more
> constrained.
> 
>  - Why do we need to have these rules?
> 
>    * protect old client applications (old NETCONF clients
>      talking to a new NETCONF server).  You're not allowed to
>      change something that makes a client that was previously
>      compliant suddenly no longer compliant.
>    * protect those importing a module
> 
>  - We're talking about rules for:
> 
>    * New building blocks (e.g., typedefs)
>    * New definitions
>    * Organizational changes (e.g., inline to named types)
>    * Bug fixes
> 
>  - Rules for adding things to an existing module:
> 
> A proposal from Balazs Lengyel:
> 
>   Balazs Lengyel provided a list of changes that Ericsson considers
>   "compatible" changes:
> 
>     - adding new optional nodes
>     - adding new RPCs
>     - extending cardinality
>     - extending the data range
>     - change of default value of an optional attribute
>     - relaxing rules on semantic change (e.g., config ->
>       non-config, read-only -> read-write
>     - adding data to notifications
>     - updates to description clauses
>     - updates to extensions
> 
>   where the policy is that if it's not on that list, it's
>   considered "an incompatible change" and shouldn't be done without
>   changing the namespace.
> 
>   Incompatible changes:
> 
>     - leaf order changes
> 
>   This fed into the subsequent suggested rules...
> 
> Changes affecting types:
> 
>   Martin Björklund asked:
> 
>     - Can you extend the value space when updating a document?
>     - Can you restrict the value space when updating a document?
> 
>   For an answer, see the general principle above.
> 
>   In the end, changes that affect storage requirements for a type
>   are not allowed.  (Editor: the consensus here is entirely
>   unclear.)
> 
> Leaf change rules:
> 
>   (Thanks to Balazs for his notes here!)
> 
>   What are you allowed / not allowed to change about a leaf
>   definition (given the general principle above):
> 
>   Changes that are permitted:
> 
>     - status with the current/deprecated/obsolete progression
>     - new typedefs
>     - new groupings
>     - expand value range
>     - remove musts
>     - new optional non-mandatory nodes
>     - allow new rpc
>     - allow new notifications
>     - allow new data in existing notifications
>     - allow new optional parameters to rpc input(?) 
>     - allow new parameters to rpc output(?) 
>     - remove mandatory
>     - reference (updated)
>     - description (semantic equivalence)
>     - length
>     - add default (Editor: unsure of this!)
>     - add new bits
>     - add new enum values at the end of the list
>     - config false ->true
>     - (all kinds of "non-changes" as well)
> 
>   Changes that are not permitted:
> 
>     - delete nodes
>     - leaf order changes (due to strict encoding order)
>     - change basic type (e.g., uint8 -> int8)
>     - change length restriction of string
>     - make a type into union
>     - no new mandatory nodes
>     - change datatype of a leaf (underlying datatype at the
>     - base of the type hierarchy)
>     - add new membertypes to a union
>     - change units
>     - change default
>     - add if-feature
>     - change the value of enum or bits
>     - add enums in the middle
> 
> Typedef change rules:
> 
>   The typedef rules discussion immediately morphed into a
>   discussion of "import by revision", which will be reported on
>   separately.  However, we reached rough consensus to proceed
>   with "import by revision", and, by deciding this, we can use
>   the same rules for typedefs as we have for leafs.  We have not
>   talked about the rules for groupings yet.
> 
>   Martin Björklund is going to take the lead in writing a
>   proposal for import by revision to cover import and include, as
>   well as the rules for what can change between revisions
>   (typedefs, groups, leafs, etc.).