Subject: [Netmod-ver-dt] Abstract and introduction

From: Robert Wilton <[email-masked]>
Date: Fri, 22 Jun 2018 11:33:21 +0100

Hi,

I've had a go at a few editorial changes to the draft:

(1) I've tweaked the abstract.
(2) I've moved the existing "introduction" to "background" and provided 
a new document introduction.
(3) I've defined module revision and version.

Please can you let me know if you think that we should incorporate these 
changes, or some aspect of these changes, or if changes/improvements are 
required.

*
*

*Abstract [**OLD]:*

    This document specifies the problems that arise today because all
    updates to YANG modules must preserve backwards compatibility.  In
    addition to explaining the implications of these problems, this
    document defines a number of requirements that a versioning scheme
    for YANG MUST and SHOULD have to be robust enough to address the
    problems.  No solutions are presented here currently, though the
    design team focusing on these problems and requirements are
    considering a number of them.

*Abstract [NEW]:*

    This document describes the problems that can arise because of the
    YANG language module update rules, that require all updates to YANG
    module preserve strict backwards compatibility.  It also defines the
    requirements on any solution designed to solve the stated problems.
    This document does not consider possible solutions, nor endorse any
    particular solution.

*
*

*Introduction [NEW] (existing Intro section moved to new background 
section):*

    This requirements document initially considers some of the existing
    YANG module update rules, then describes the problems that arise due
    to those rules embracing strict backwards compatibility, and finally
    defines requirements on any solution that may be designed to solve
    these problems by providing an alternative YANG versioning strategy.

    The requirements defined in Section 5 make use of [RFC2119] language,
    which is to be interpreted as follows:

    o  "MUST/REQUIRED - indicates a requirement that any solution has to
       meet to be considered as a viable solution"

    o  "SHOULD - indicates a requirement that is strongly desirable for a
       solution to meet."

    Solutions can be evaluated against these requirements.  Any solution
    that does not meet all of the MUST/REQUIRED requirements can be
    dismissed as being insufficient, otherwise a solution that satisfies
    more of the SHOULD requirements shall be regarded favorably against a
    solution that satisfies less of them.  An ideal solution would
    satisfy all the specified requirements.

    In addition to the explicitly stated requirements, solutions would
    also expect to be evaluated against standard engineering principles
    such as:

    o  "Overall complexity of the solution, both in specification and
       implementation"

    o  "Anticipated effort required for implementation (both client and
       servers)"

    o  "Viability, and anticipated effort required to upgrade from the
       existing versioning strategy to the new versioning strategy."

*
*

*Terminology [NEW]:*

    In addition, this document uses the following terminology:

    o  YANG module revision: An instance of a YANG module, with no
       implied ordering or backwards compatibility between different
       revisions of the same module."

    o  YANG module version: A YANG module revision, but also with an
       implied partial ordering relationship between other versions of
       the same module.  Each module version must be uniquely
       identifiable.

------------

*All text up to chapter 4:*

Network Working Group                                     J. Clarke, Ed.
Internet-Draft                                       Cisco Systems, Inc.
Intended status: Standards Track                           June 22, 2018
Expires: December 24, 2018

                   YANG Module Versioning Requirements
                draft-verdt-netmod-yang-versioning-reqs-00

Abstract

    This document describes the problems that can arise because of the
    YANG language module update rules, that require all updates to YANG
    module preserve strict backwards compatibility.  It also defines the
    requirements on any solution designed to solve the stated problems.
    This document does not consider possible solutions, nor endorse any
    particular solution.

Status of This Memo

    This Internet-Draft is submitted in full conformance with the
    provisions of BCP 78 and BCP 79.

    Internet-Drafts are working documents of the Internet Engineering
    Task Force (IETF).  Note that other groups may also distribute
    working documents as Internet-Drafts.  The list of current Internet-
    Drafts is at https://datatracker.ietf.org/drafts/current/.

    Internet-Drafts are draft documents valid for a maximum of six months
    and may be updated, replaced, or obsoleted by other documents at any
    time.  It is inappropriate to use Internet-Drafts as reference
    material or to cite them other than as "work in progress."

    This Internet-Draft will expire on December 24, 2018.

Copyright Notice

    Copyright (c) 2018 IETF Trust and the persons identified as the
    document authors.  All rights reserved.

    This document is subject to BCP 78 and the IETF Trust's Legal
    Provisions Relating to IETF Documents
    (https://trustee.ietf.org/license-info) in effect on the date of
    publication of this document.  Please review these documents
    carefully, as they describe your rights and restrictions with respect
    to this document.  Code Components extracted from this document must
    include Simplified BSD License text as described in Section 4.e of

Clarke                  Expires December 24, 2018               [Page 1]

Internet-Draft        YANG Versioning Requirements             June 2018

    the Trust Legal Provisions and are provided without warranty as
    described in the Simplified BSD License.

Table of Contents

    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
    2.  Background  . . . . . . . . . . . . . . . . . . . . . . . . .   3
    3.  Terminology and Conventions . . . . . . . . . . . . . . . . .   4
    4.  The Problem Statement . . . . . . . . . . . . . . . . . . . .   4
      4.1.  Slow Standardization  . . . . . . . . . . . . . . . . . .   4
      4.2.  Some YANG Modules Are Not Backward Compatible . . . . . .   4
      4.3.  Non-Backward Compatible Errors  . . . . . . . . . . . . .   5
      4.4.  No way to easily decide whether a change is Backward
            Compatible  . . . . . . . . . . . . . . . . . . . . . . .   5
      4.5.  No good way to specify which module revision to import  .   6
      4.6.  Early Warning about Removal . . . . . . . . . . . . . . .   7
      4.7.  Clear Indication of Node Support  . . . . . . . . . . . .   7
    5.  Requirements of a YANG Versioning Solution  . . . . . . . . .   8
    6.  Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  10
    7.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
    8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
    9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  10
      9.1.  Normative References  . . . . . . . . . . . . . . . . . .  10
      9.2.  Informative References  . . . . . . . . . . . . . . . . .  11
    Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  11

1.  Introduction

    This requirements document initially considers some of the existing
    YANG module update rules, then describes the problems that arise due
    to those rules embracing strict backwards compatibility, and finally
    defines requirements on any solution that may be designed to solve
    these problems by providing an alternative YANG versioning strategy.

    The requirements defined in Section 5 make use of [RFC2119] language,
    which is to be interpreted as follows:

    o  "MUST/REQUIRED - indicates a requirement that any solution has to
       meet to be considered as a viable solution"

    o  "SHOULD - indicates a requirement that is strongly desirable for a
       solution to meet."

    Solutions can be evaluated against these requirements.  Any solution
    that does not meet all of the MUST/REQUIRED requirements can be
    dismissed as being insufficient, otherwise a solution that satisfies
    more of the SHOULD requirements shall be regarded favorably against a

Clarke                  Expires December 24, 2018               [Page 2]

Internet-Draft        YANG Versioning Requirements             June 2018

    solution that satisfies less of them.  An ideal solution would
    satisfy all the specified requirements.

    In addition to the explicitly stated requirements, solutions would
    also expect to be evaluated against standard engineering principles
    such as:

    o  "Overall complexity of the solution, both in specification and
       implementation"

    o  "Anticipated effort required for implementation (both client and
       servers)"

    o  "Viability, and anticipated effort required to upgrade from the
       existing versioning strategy to the new versioning strategy."

2.  Background

    The YANG data modeling language [RFC7950] specifies strict rules for
    updating YANG modules (see section 11 "Updating a Module").  Citing a
    few of the relevant rules:

    1.  "As experience is gained with a module, it may be desirable to
        revise that module.  However, changes to published modules are
        not allowed if they have any potential to cause interoperability
        problems between a client using an original specification and a
        server using an updated specification."

    2.  "Note that definitions contained in a module are available to be
        imported by any other module and are referenced in "import"
        statements via the module name.  Thus, a module name MUST NOT be
        changed.  Furthermore, the "namespace" statement MUST NOT be
        changed, since all XML elements are qualified by the namespace."

    3.  "Otherwise, if the semantics of any previous definition are
        changed (i.e., if a non-editorial change is made to any
        definition other than those specifically allowed above), then
        this MUST be achieved by a new definition with a new identifier."

    4.  "deprecated indicates an obsolete definition, but it permits new/
        continued implementation in order to foster interoperability with
        older/existing implementations."

    It is the rules described above, along with other similar rules, that
    causes the problems described in Section 4.

Clarke                  Expires December 24, 2018               [Page 3]

Internet-Draft        YANG Versioning Requirements             June 2018

3.  Terminology and Conventions

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
    document are to be interpreted as described in [RFC2119].

    In addition, this document uses the following terminology:

    o  YANG module revision: An instance of a YANG module, with no
       implied ordering or backwards compatibility between different
       revisions of the same module."

    o  YANG module version: A YANG module revision, but also with an
       implied partial ordering relationship between other versions of
       the same module.  Each module version must be uniquely
       identifiable.

Thanks,
Rob

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 22 Jun 2018 12:57:34 +0200

On 6/22/2018 12:33 PM, Robert Wilton
wrote:

Hi,

(2) I've moved the existing "introduction" to "background" and
provided a new document introduction.

Please can you let me know if you think that we should
incorporate these changes, or some aspect of these changes, or
if changes/improvements are required.

Abstract [OLD]:

Abstract [NEW]:

BALAZS: Good

Introduction [NEW] (existing Intro section moved to new
background section):

BALAZS: I  do not see the need for the later
parts of this text. RFC 2119 defines the term MUST

and SHOULD. Good engineering practices should apply without
mentioning them.

Terminology [NEW]:

------------

All text up to chapter 4:

Abstract

Status of This Memo

Copyright Notice

Table of Contents

1. Introduction

2. Background

Thanks,

Rob

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

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

---

From: Joe Clarke <[email-masked]>
Date: Fri, 22 Jun 2018 08:46:26 -0400

On 6/22/18 06:57, Balazs Lengyel wrote:
> BALAZS: I  do not see the need for the later parts of this text. RFC
> 2119 defines the term MUST
> and SHOULD. Good engineering practices should apply without mentioning
> them.

Agreed.  I don't see a need to quote 2119 directly here.

I am fine with the other changes.  In particular, I agree with the new
terminology around version.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Fri, 22 Jun 2018 14:20:13 +0100

> Agreed.  I don't see a need to quote 2119 directly here.
So I added the explicit definition of how MUST, SHOULD applies to 
requirements based on Benoit's comments in the meeting yesterday 
regarding the IESG, and that if we applying a particular meaning to the 
RFC 2119 definitions as they apply to the requirements we should state it.

The reason that I added text about engineering practices is because a 
complex solution that covers every requirement is not necessarily better 
than a simpler solution that only covers the MUST requirements.

What if it was curtailed.  E.g.

1.  Introduction

    In addition to the explicitly stated requirements, solutions would
    also expect to be evaluated against standard engineering principles,
    e.g., complexity, ease of implementation, etc.

> terminology around version.
OK.  I'll push what has been agreed so far to github.

Thanks,
Rob

> .

---

From: Joe Clarke <[email-masked]>
Date: Fri, 22 Jun 2018 09:26:20 -0400

> What if it was curtailed.  E.g.

I thought 2119 defined those terms with respect to "requirements" well
as it is.  And this doc likely won't see the IESG's eyes.  So as long as
the WG is okay, then it should be fine.

Again, not a shed worth painting with too many coats.  What you have
here is not wrong, and perhaps does add explicit clarity.

I would still drop the engineering statement as it doesn't give clear
guidance on which would win out (even though many may infer it).

> OK.  I'll push what has been agreed so far to github.

Thanks.

Joe

---

From: Benoit Claise <[email-masked]>
Date: Fri, 22 Jun 2018 12:43:06 -0700

On 6/22/2018 6:26 AM, Joe Clarke wrote:
>> regarding the IESG,
"I won't die on that hill", using Joe's expression from the last call.

Regards, Benoit
>> and that if we applying a particular meaning to the