Subject: [Netmod-ver-dt] Current requirements text

From: Robert Wilton <[email-masked]>
Date: Thu, 21 Jun 2018 14:35:00 +0100

This is what I have as the latest, I will also push this to github.  
Perhaps worth checking that I've not missed any updates.

Thanks,
Rob

4.  Requirements of a YANG Versioning Solution

    The following is a list of requirements that a solution to the
    problems mentioned above MUST or SHOULD have.  The list is grouped by
    similar requirements but is not presented in a set priority order.

    1.  Requirements related to making non-backwards compatible updates
        to modules:

        1.1  A mechanism is REQUIRED to update a module in a non-
             backwards compatible way without forcing all modules with
             import dependencies on the updated module from being updated
             at the same time (e.g. to change its import to use a new
             module name).

        1.2  A mechanism is REQUIRED to update a module in a non-
             backwards compatible way without forcing all clients/servers
             to access data nodes in the model on new paths, or in a new
             module namespace.  Specifically, if a particular data node
             is updated in a non backwards compatible way then it may be
             desirable for it to be available on the same path and in the
             same module namespace.

        1.3  A refined form of YANG's 'import' statement MUST be provided
             that is more restrictive than "import any revision" and less
             restrictive than "import a specific revision".  Once non-
             backwards compatible changes to modules are allowed, the
             refined import statement is used to express the correct
             dependency between modules.

    2.  Requirements related to identifying changes between different
        module revisions:

        2.1  Readers of modules, and tools that use modules, MUST be able
             to determine whether changes between two revisions of a
             module constitute a backwards compatible or non-backwards
             compatible version change.  In addition, it MAY be helpful
             to identify whether changes represent bug fixes, new
             functionality, or both.

        2.2  A mechanism SHOULD be defined to determine whether data
             nodes between two arbitrary YANG module revisions have (i)
             not changed, (ii) changed in a backwards compatible way,
             (iii) changed in a non-backwards compatible way.

    3.  Requirements related to supporting existing clients in a
        backwards compatible way:

        3.1  The solution MUST provide a mechanism to allow servers to
             support existing clients in a backwards compatible way.

        3.2  The solution MUST provide a mechanism to allow servers to
             simultaneously support clients using different revisions of
             modules.  A client's choice of particular revision of one or
             more modules may restrict the particular revision of other
             modules that may be used in the same request or session.

    4.  Requirements related to managing and documenting the life cycle
        of data nodes:

        4.1  A mechanism is REQUIRED to allow a client to determine
             whether deprecated nodes are implemented by the server.

        4.2  If a data node is deprecated or obsolete then it MUST be
             possible to document in the YANG module what alternatives
             exist, the reason for the status change, or any other status
             related information.

        4.3  A mechanism is REQUIRED to indicate that certain definitions
             in a YANG module will become status obsolete in future
             revisions but definitions marked as such MUST still be
             implemented by compliant servers.

        4.4  If multiple revisions of a YANG module are published, then
             the solution SHOULD allow for bug fixes to be made to an
             older revision of the module.

    5.  Requirements related to documentation and education:

        5.1  The solution SHOULD provide guidance to model authors and
             clients on how to use the new YANG versioning scheme.

        5.2  The solution is REQUIRED to describe how to transition from
             the existing YANG 1.0/1.1 versioning scheme to the new
             scheme.

        5.3  PROPOSED: The solution MUST describe how the versioning
             scheme applies to instance data, and references to instance
             data, for which the schema definition has been updated in a
             non backwards compatible way.

---

From: Balazs Lengyel <[email-masked]>
Date: Thu, 21 Jun 2018 15:57:42 +0200

Mostly OK. (last mail before the meeting)

On 6/21/2018 3:35 PM, Robert Wilton
wrote:

BALAZS: its not really the status obsolete
that is a problem, but a removed implementation. So I would use

".. that certain schema nodes implementation will be removed in
the future ..."

By using obsolete we go back to the problem of explaining that
obsolete means ...

Also if you just deprecate something AND remove it, it is still a
problem. The requirements allow that.

BALAZS: This could actually include my "new"
requirement about risks and wen to change name.

--
Balazs Lengyel Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909 email: [email-masked]

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 21 Jun 2018 16:07:00 +0200

On Thu, Jun 21, 2018 at 03:57:42PM +0200, Balazs Lengyel wrote:
>    On 6/21/2018 3:35 PM, Robert Wilton wrote:
> 
>    BALAZS: its not really the status obsolete that is a problem, but a
>    removed implementation. So I would use
>    ".. that certain schema nodes implementation will be removed in the future
>    ..."
>    By using obsolete we go back to the problem of explaining that obsolete
>    means ...
>    Also if you just deprecate something AND remove it, it is still a problem.
>    The requirements allow that.

I suggested "become obsolete" and I believe it does not matter whether
you use the RFC 7950 interpretation of obsolete or natural language
obsolete. The phrase "certain schema nodes implementation will be
removed" does not seem to improve things.

/js

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