Re: [Netmod-ver-dt] Comments on the guidelines chapter

"Reshad Rahman (rrahman)" <rrahman@cisco.com> Wed, 05 June 2019 20:53 UTC

Return-Path: <rrahman@cisco.com>
X-Original-To: netmod-ver-dt@ietfa.amsl.com
Delivered-To: netmod-ver-dt@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 14E9C120144 for <netmod-ver-dt@ietfa.amsl.com>; Wed, 5 Jun 2019 13:53:00 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -14.499
X-Spam-Level:
X-Spam-Status: No, score=-14.499 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_HI=-5, SPF_PASS=-0.001, URIBL_BLOCKED=0.001, USER_IN_DEF_DKIM_WL=-7.5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=cisco.com header.b=Y8/vbNmd; dkim=pass (1024-bit key) header.d=cisco.onmicrosoft.com header.b=BXSQJHoH
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id tzTGTvBcF8q7 for <netmod-ver-dt@ietfa.amsl.com>; Wed, 5 Jun 2019 13:52:56 -0700 (PDT)
Received: from rcdn-iport-3.cisco.com (rcdn-iport-3.cisco.com [173.37.86.74]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 88FEA12013B for <netmod-ver-dt@ietf.org>; Wed, 5 Jun 2019 13:52:56 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=45619; q=dns/txt; s=iport; t=1559767976; x=1560977576; h=from:to:subject:date:message-id:references:in-reply-to: mime-version; bh=5aFQ5amKA7rOs+53hxpiUYGEya7ML6L6lAM67nVO/KQ=; b=Y8/vbNmdO3daV0SFt2fxB5wGtyKyW0sSr7/tc926+xcqacTgWjXEUbk5 V2LBluGydFcYIBBJPDRafVeqOcvYBLCEFjVxJd7aWaZJeQou78+3zjmyR /pfH6/dkmX6nDnpO2guPfX8qzFAq+xpMg6ZaC7Ebd6GGCke3mRb3L8Mxe 4=;
IronPort-PHdr: 9a23:10eaFhOGdehk1nXb4GYl6mtXPHoupqn0MwgJ65Eul7NJdOG58o//OFDEu60/l0fHCIPc7f8My/HbtaztQyQh2d6AqzhDFf4ETBoZkYMTlg0kDtSCDBjhNvfqaiU8NM9DT1RiuXq8NBsdFQ==
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: A0BIAAA9K/hc/5ldJa1cChwBAQEEAQEHBAEBgVEHAQELAYEOL1ADalUgBAsoCoQKg0cDhFKKC4JXlzCBLhSBEANUCQEBAQwBAS0CAQGEQAIXgj8jNAkOAQMBAQQBAQIBBG0cDIVKAQEBAwESEQQZAQE4BAsCAQgRAwECIQEJAgICMB0IAQEEARIbB4MAAYEdTQMODwGbfQKBOIhfcX4zgnkBAQWCR4I8GIIPCYE0AYtaF4FAP4ERJx+CTD6EGRMCNhiCUjKCJos1gm2EaogfGIxnagkCgg6TOhuCI4xsh3CNDoEplQcCBAIEBQIOAQEFgU84gVhwFWUBgkGCDxESg02KU3KBKY1FAYEgAQE
X-IronPort-AV: E=Sophos;i="5.60,556,1549929600"; d="scan'208,217";a="558149539"
Received: from rcdn-core-2.cisco.com ([173.37.93.153]) by rcdn-iport-3.cisco.com with ESMTP/TLS/DHE-RSA-SEED-SHA; 05 Jun 2019 20:52:55 +0000
Received: from XCH-RCD-015.cisco.com (xch-rcd-015.cisco.com [173.37.102.25]) by rcdn-core-2.cisco.com (8.15.2/8.15.2) with ESMTPS id x55Kqtff003394 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=FAIL) for <netmod-ver-dt@ietf.org>; Wed, 5 Jun 2019 20:52:55 GMT
Received: from xhs-rcd-003.cisco.com (173.37.227.248) by XCH-RCD-015.cisco.com (173.37.102.25) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Wed, 5 Jun 2019 15:52:54 -0500
Received: from xhs-rtp-002.cisco.com (64.101.210.229) by xhs-rcd-003.cisco.com (173.37.227.248) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Wed, 5 Jun 2019 15:52:53 -0500
Received: from NAM02-BL2-obe.outbound.protection.outlook.com (64.101.32.56) by xhs-rtp-002.cisco.com (64.101.210.229) with Microsoft SMTP Server (TLS) id 15.0.1473.3 via Frontend Transport; Wed, 5 Jun 2019 16:52:52 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cisco.onmicrosoft.com; s=selector2-cisco-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=5aFQ5amKA7rOs+53hxpiUYGEya7ML6L6lAM67nVO/KQ=; b=BXSQJHoHtRXJQx+gUF0vLntXcZpwVnFfuz6qwBiLWduY0f9mo4VfwalXCB2zKwb4yWBxhBwup3J+5l78GFeDuN7SEuh8FJCuYIuavQVKJaTyH4gkng7HIsZIC+CsGCWQ0cuTkJS3+UPtjJvSjsf3fFibXl0Rgs9Ht42ZZyB1Mf0=
Received: from DM5PR1101MB2105.namprd11.prod.outlook.com (10.174.104.151) by DM5PR1101MB2122.namprd11.prod.outlook.com (10.174.106.19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1943.22; Wed, 5 Jun 2019 20:52:51 +0000
Received: from DM5PR1101MB2105.namprd11.prod.outlook.com ([fe80::6ce2:350d:6bed:7dde]) by DM5PR1101MB2105.namprd11.prod.outlook.com ([fe80::6ce2:350d:6bed:7dde%2]) with mapi id 15.20.1965.011; Wed, 5 Jun 2019 20:52:51 +0000
From: "Reshad Rahman (rrahman)" <rrahman@cisco.com>
To: "Rob Wilton (rwilton)" <rwilton@cisco.com>, "netmod-ver-dt@ietf.org" <netmod-ver-dt@ietf.org>
Thread-Topic: Comments on the guidelines chapter
Thread-Index: AdUbv4OSRZIqBFosSQueZJ2vAPqisf///y+A
Date: Wed, 05 Jun 2019 20:52:51 +0000
Message-ID: <0E6B8ACB-8B74-4C2B-ADBB-F3CF8EBA7DF0@cisco.com>
References: <BYAPR11MB26316C8F19B99FA99F86D012B5160@BYAPR11MB2631.namprd11.prod.outlook.com>
In-Reply-To: <BYAPR11MB26316C8F19B99FA99F86D012B5160@BYAPR11MB2631.namprd11.prod.outlook.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
user-agent: Microsoft-MacOutlook/10.10.6.190114
authentication-results: spf=none (sender IP is ) smtp.mailfrom=rrahman@cisco.com;
x-originating-ip: [173.38.117.73]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: b6acd69e-3de2-45ff-0f11-08d6e9f7c66f
x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(4627221)(201703031133081)(201702281549075)(8990200)(5600148)(711020)(4605104)(1401327)(2017052603328)(7193020); SRVR:DM5PR1101MB2122;
x-ms-traffictypediagnostic: DM5PR1101MB2122:
x-ms-exchange-purlcount: 2
x-microsoft-antispam-prvs: <DM5PR1101MB21221B1875D757D697DD3BCCAB160@DM5PR1101MB2122.namprd11.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:10000;
x-forefront-prvs: 00594E8DBA
x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(376002)(39860400002)(346002)(366004)(396003)(136003)(51444003)(199004)(189003)(58126008)(76176011)(110136005)(66946007)(66556008)(66476007)(64756008)(91956017)(25786009)(53546011)(102836004)(6506007)(446003)(76116006)(82746002)(6116002)(66446008)(68736007)(6486002)(8936002)(478600001)(3846002)(7736002)(66066001)(33656002)(6246003)(6436002)(5660300002)(99286004)(6512007)(54896002)(6306002)(81166006)(14454004)(9326002)(53936002)(71200400001)(81156014)(186003)(8676002)(86362001)(71190400001)(83716004)(229853002)(2906002)(11346002)(476003)(26005)(2616005)(316002)(14444005)(256004)(73956011)(66574012)(2501003)(486006)(36756003); DIR:OUT; SFP:1101; SCL:1; SRVR:DM5PR1101MB2122; H:DM5PR1101MB2105.namprd11.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1;
received-spf: None (protection.outlook.com: cisco.com does not designate permitted sender hosts)
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam-message-info: rMZc6NcRtazmQQi67r8xRw08gsfWyE4KEVu6SEZ0HkIcBpX/A8mvENdqkG1Y0p4zX16UEgBa5h68et1frVoqzgLJ3I2wgmSMvXRrweDlcWz9eXpJStH+BW+zNuWTAxhwjDAbFy0T/Dq3tNBUiBrhkX6H6G+KgckpxumPa4rnawzaB1+RzPIdaxYtMgczD5B7tz88KXNPSSlxJ7lVcEBKZalAhoMmrWhwYKKw/BGRJHj0tyaKDT303ic+H+By8NlboJiiJXC/BDECqctnXfm+IZkIw2EvsNNF4whjLNFOVkkKtFN8oH+LiklRQJZonvah08i/hvshm0Uk6oPR5A94BQp/VoeghSHo7P+5yremjgukKR0MPivukxBtttkzGx8iioWcXD9veOwpnL6y8HvYVRJHRMMxJPH0+Z8oyQlLKTU=
Content-Type: multipart/alternative; boundary="_000_0E6B8ACB8B744C2BADBBF3CF8EBA7DF0ciscocom_"
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-Network-Message-Id: b6acd69e-3de2-45ff-0f11-08d6e9f7c66f
X-MS-Exchange-CrossTenant-originalarrivaltime: 05 Jun 2019 20:52:51.3753 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 5ae1af62-9505-4097-a69a-c1553ef7840e
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: rrahman@cisco.com
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM5PR1101MB2122
X-OriginatorOrg: cisco.com
X-Outbound-SMTP-Client: 173.37.102.25, xch-rcd-015.cisco.com
X-Outbound-Node: rcdn-core-2.cisco.com
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod-ver-dt/hGIKLyGi63stNjEglVWGQjoCrHA>
Subject: Re: [Netmod-ver-dt] Comments on the guidelines chapter
X-BeenThere: netmod-ver-dt@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: NetMod WG YANG Model Versioning Design Team <netmod-ver-dt.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod-ver-dt>, <mailto:netmod-ver-dt-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod-ver-dt/>
List-Post: <mailto:netmod-ver-dt@ietf.org>
List-Help: <mailto:netmod-ver-dt-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod-ver-dt>, <mailto:netmod-ver-dt-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 05 Jun 2019 20:53:00 -0000

Hi Rob,

Yes we can discuss in the meeting. Inline.

From: "Rob Wilton (rwilton)" <rwilton@cisco.com>
Date: Wednesday, June 5, 2019 at 12:58 PM
To: "netmod-ver-dt@ietf.org" <netmod-ver-dt@ietf.org>, "Reshad Rahman (rrahman)" <rrahman@cisco.com>
Subject: Comments on the guidelines chapter

Hi Reshad,

Sorry that these have been so late, but here are some comments on the guidelines chapter.  Potentially we can discuss tomorrow, if needed.

>6.1.  Guidelines for YANG module authors

I think that this section should state that is updates RFC8407 sections 4.7 and 4.8, and I think that we should check the text against this existng BCP.
<RR> Ack. I thought I had done that, but missed it.

I think that the text also needs to cover:
(i) Adding a "rev:nbc-changes;" if and only if there are NBC changes relative to the previous revision.
(ii) Fixing RFC8407 section 4.7's "The revision date substatement within the import statement SHOULD be present if any groupings are used from the external module.".
(iii) Fixing RFC8409 section 4.7's "The revision date substatement within the include statement SHOULD be present if any groupings are used from the external submodule." - I think that we want this to be a MUST otherwise the module doesn't have a stable definition because the the module revision does not uniquely identify its content.
(iv) Some text stating that removing old revision statements from a modules revision history could break import by revision, and hence it might be better to retain them, unless it is known that all depencencies have been updated.  An alternative solution, if the revision section is too long, would be remove, or curtail, the older description statements associated with old historical revisions.
(v) Some guidance about whether updating the revision in import revision-or-derived is a BC or NBC change.  I think that it is NBC is the imported module has been changed in an NBC way between the revision dates.

>
>   NBC changes to YANG modules may cause problems to clients, who are
>   consumers of YANG models, and SHOULD be avoided.  YANG module authors
>   are recommended to minimize NBC changes and keep changes BC whenever
>   possible.

I think "SHOULD be avoided" is too strong.  Perhaps:

NBC changes to YANG modules may cause problems to clients, who are
consumers of YANG models, and hence YANG module authors are
RECOMMENDED to minimize NBC changes and keep changes BC whenever
possible.

<RR> Good with me.

My counter argument is that there are somecases (e.g. bugfixes), where an NBC change makes sense because it should not break any clients.

<RR> Ack.

>
>   When NBC changes are introduced, consideration should be given to the
>   impact on clients and YANG module authors SHOULD try to mitigate that
>   impact.

OK.


>
>6.1.1.  Making non-backwards-compatible changes to a YANG module
>
>   There are various valid situations where a YANG module has to be
>   modified in a non-backwards-compatible way.  Here are the different
>   ways in which this can be done:
>
>   o  NBC changes can be done incrementally using the 'deprecated'
>      status to provide clients time to adapt to NBC changes.

I would suggest caveating this to:

  o  NBC changes can sometimes be done incrementally using the 'deprecated'
     status to provide clients time to adapt to NBC changes.
<RR> OK.

E.g. I'm still to be convinced that in the mainline case that configuration can be fixed incrementally.
<RR> I think the issue is supporting both at the same time. E.g. in the vpn-id example where the type is changed from integer to string,  it can be done incrementally but supporting both at the same time on a server is an issue (mapping values etc).

>
>   o  NBC changes are done at once, i.e. without using 'status'
>      statements.  This has a big impact on clients.

"This has a big impact on clients." => "Depending on the change, this may have a big impact on clients."

<RR> Ack.

>
>   o  If the server can support multiple versions of the YANG module or
>      of YANG packages(as specified in
>      [I-D.rwilton-netmod-yang-packages]), and allows the client to
>      select the version (as per
>      [I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be
>      done without using 'status' statements.  Clients would be required
>      to select the version which they support and the NBC change would
>      have no impact on them

OK.


>
>   Here are some guidelines on how non-backwards compatible changes can
>   be made incrementally:

Perhaps, alter this to something like:

Here are some guidelines on how non-backwards compatible changes can be made incrementally, with the assumption that deprecated nodes are implemented by the srever, and obselete nodes are not:
<RR> Good with me.

>
>   1.  The changes should be made gradually, e.g. a data node's status
>       SHOULD NOT be changed directly from "current" to "obsolete" (see
>       Section 4.7 of [RFC8407]), instead the status SHOULD first be
>       marked "deprecated" and then when support is removed its status
>       MUST be changed to "obsolete".  Instead of using the "obsolete"
>       status, the data node MAY be removed from the model but this has
>       the risk of breaking modules which import the modified module.
>
>   2.  A node with status "deprecated" MUST be supported for the
>       solution described here to function properly.

As above, I think that this could be merged into the first sentence.
<RR> So just take bullet 2 out?

>
>   3.  A node with status "deprecated" SHOULD be available for at least
>       one year before its status is changed to "obsolete", see
>       Section 4.7 of [RFC8407].

I'm not sure whether we need to even state this one (since it is already in RFC8407).
<RR> Yes, and I’d like to avoid this statement since it’s contentious.


>
>   4.  Support for a node which is "obsolete" is indicated by the node
>       "obsolete-nodes-present, see Section 4.

As above, I think that this coudl be merged into the first sentence.
>
>
>
>Claise, et al.          Expires December 1, 2019               [Page 15]
>

>Internet-Draft           YANG Module Versioning                 May 2019
>
>
>   5.  The new extension "status-description" SHOULD be used for nodes
>       which are "obsolete" or "deprecated".

Should we indicate what information should be included:
- Reason for deprecation (if interesting)
- Replacement node (if known)
- Release/time that the node is anticipated to be obsoleted.

<RR> The last 2 points are  mentioned in the following bullets. I’ll add the 1st point.

Should we also indicate that "status-description" can be used with "status current" to provide forewarning that it could be deprecated, or does that mean that the node is already deprecated?

>
>   6.  For status "deprecated", the "status-description" SHOULD also
>       indicate until when support for the node is guaranteed.  If there
>       is a replacement data node, rpc, action or notification for the
>       deprecated node, this SHOULD be stated in the "status-
>       description".

I think that the first "SHOULD" should be a "MAY" because it is hard to foretell the future.  Alternatively, or perhaps in addition, it should be caveated with an "if known".
<RR> if known.

I think that this paragraph should also cover "reason for deprecated (if interesting)", and some of the status-description information also applies, and should be preserved when it becomes status-obsolete.


>
>   7.  When obsoleting or deprecating data nodes, the "deprecated" or
>       "obsolete" status SHOULD be applied at the highest possible level
>       in the data tree.  For example, when deprecating all data nodes
>       in a container, the "deprecated" status SHOULD be applied to the
>       container.  For clarity, the status MAY be added in all the
>       affected nodes but the status-description SHOULD be added only at
>       the highest level in the tree.

I would suggest rephasing to something like:

   7.  When obsoleting or deprecating data nodes, the "deprecated" or
       "obsolete" status SHOULD be applied at the highest possible level
       in the data tree with an appropriate status-description.  For
       clarity, status statement SHOULD also be applied to all descendent
       data nodes, but status-description does not need to be repeated
       if it does not introduce any additional information.
<RR> Good with me.

>
>   See Appendix A.2 for examples on how non-backwards-compatible changes
>   can be made.
>
>6.2.  Versioning Considerations for Clients
>
>   Guidelines for clients of modules using the new module revision
>   update procedure:
>
>   o  Clients SHOULD be liberal when processing data received from a
>      server.  For example, the server may have increased the range of
>      an operational node causing the client to receive a value which is
>      outside the range of the YANG model revision it was coded against.
>
>   o  Clients SHOULD monitor changes to published YANG modules through
>      their revision history, and use appropriate tooling to understand
>      the specific changes between module revision.  In particular,
>      clients SHOULD NOT migrate to NBC revisions of a module without
>      considering the specific NBC changes.

considering -> "understanding any potential impact of"
<RR> Ack.

Regards,
Reshad.

>
>   o  Clients SHOULD plan to make changes to match published status
>      changes.  When a node's status changes from "current" to
>      "deprecated", clients SHOULD plan to stop using that node in a
>      timely fashion.  When a node's status changes to "obsolete",
>      clients MUST stop using that node.

Thanks,
Rob