Re: [netmod] All IETF YANG modules MUST include revision-label statements

"Rob Wilton (rwilton)" <rwilton@cisco.com> Wed, 01 April 2020 15:05 UTC

Return-Path: <rwilton@cisco.com>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id E5D013A1112 for <netmod@ietfa.amsl.com>; Wed, 1 Apr 2020 08:05:49 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -9.597
X-Spam-Level:
X-Spam-Status: No, score=-9.597 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, 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=L55J8Jv3; dkim=pass (1024-bit key) header.d=cisco.onmicrosoft.com header.b=twVVrepv
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 232bDs3moz5O for <netmod@ietfa.amsl.com>; Wed, 1 Apr 2020 08:05:47 -0700 (PDT)
Received: from rcdn-iport-7.cisco.com (rcdn-iport-7.cisco.com [173.37.86.78]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 150933A1117 for <netmod@ietf.org>; Wed, 1 Apr 2020 08:05:47 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=33352; q=dns/txt; s=iport; t=1585753547; x=1586963147; h=from:to:cc:subject:date:message-id:references: in-reply-to:mime-version; bh=FhA4F6oxPvGaR8J5wSYR41jl3dq0xbF0vN5gQ1bUULQ=; b=L55J8Jv32T+y1/CkFI80bkrLYmZaZMI9tfTBRHCRgmBxgVhjS1xjWz+a AU3cNixugvRW49TxuoS28hmFgDCZjIdZY/0u3g+jEqiKllTWRSx6dGxJn szCdOzCQcM/Bzg+X+efOU7XwGPg4rIi+MIFJARFCcLo6csJ9DXqueMWiR I=;
IronPort-PHdr: =?us-ascii?q?9a23=3A2Sh8ZhI2BqcimL1brtmcpTVXNCE6p7X5OBIU4Z?= =?us-ascii?q?M7irVIN76u5InmIFeBvad2lFGcW4Ld5roEkOfQv636EU04qZea+DFnEtRXUg?= =?us-ascii?q?Mdz8AfngguGsmAXFfkLfr2aCoSF8VZX1gj9Ha+YgBY?=
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0BbDgDzrIRe/4cNJK1mHgELHIMgL1A?= =?us-ascii?q?FbFggBAsqCoNQQINFA4ptgl+YHYJSA1QKAQEBDAEBLQIEAQGBUIJ0AheCISQ?= =?us-ascii?q?4EwIDAQELAQEFAQEBAgEFBG2FVgyFcAEBAQEDDAYRChMBATcBDwIBBgIRBAE?= =?us-ascii?q?BIQcDAgICMBQJCAIEDgUIEQIHgwWBfk0DLgEDkmiQZwKBOYhidYEygn8BAQW?= =?us-ascii?q?FFhiCDAmBOIwxGoFBP4ERR4FPUC4+hCUrNIJcMoIsjWZUAoJIhX4kigqPVAq?= =?us-ascii?q?CPZc9gkyIM5BzkHmaPAIEAgQFAg4BAQWBaSKBWHAVgydQGA2OHQwXg1CKVXS?= =?us-ascii?q?BKYtJAiYHgQQBgQ8BAQ?=
X-IronPort-AV: E=Sophos;i="5.72,332,1580774400"; d="scan'208,217";a="739969117"
Received: from alln-core-2.cisco.com ([173.36.13.135]) by rcdn-iport-7.cisco.com with ESMTP/TLS/DHE-RSA-SEED-SHA; 01 Apr 2020 15:05:45 +0000
Received: from XCH-RCD-003.cisco.com (xch-rcd-003.cisco.com [173.37.102.13]) by alln-core-2.cisco.com (8.15.2/8.15.2) with ESMTPS id 031F5jEa027539 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=FAIL); Wed, 1 Apr 2020 15:05:45 GMT
Received: from xhs-rcd-003.cisco.com (173.37.227.248) by XCH-RCD-003.cisco.com (173.37.102.13) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Wed, 1 Apr 2020 10:05:44 -0500
Received: from xhs-aln-002.cisco.com (173.37.135.119) by xhs-rcd-003.cisco.com (173.37.227.248) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Wed, 1 Apr 2020 10:05:44 -0500
Received: from NAM12-MW2-obe.outbound.protection.outlook.com (173.37.151.57) by xhs-aln-002.cisco.com (173.37.135.119) with Microsoft SMTP Server (TLS) id 15.0.1497.2 via Frontend Transport; Wed, 1 Apr 2020 10:05:43 -0500
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=VZmF2ZT3ahT5eh6TEPHkkC7BIs1XTRr9lSTXKpe6sDxRrv9GiELK5ifQoLejnGiVG73Qw8Pg2PO59HcwGyWh4lQV2OvnVplGIwY0SWdPVSSnhyHlGZAHCz1saMpOtPkRRV+JJNZGpHGY5G6nFlMo61Yumv6yBl57brMb3Dm8JwJZuSh6VyS0f7WtBR3hNek1debdKxcSGZtqmlovnLgCE/itM23j5X6YMXDCbeyawShpTv1m7xLdqr5b7OFzc5Y9HBdOM3NhdyFPstKcVwQpclAdMPVZPXMXY/T1ziTyncIitHZ5TkOT7IXNOrzXpi7YSd7tOc7Adqc08D+HUuYQgA==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=FhA4F6oxPvGaR8J5wSYR41jl3dq0xbF0vN5gQ1bUULQ=; b=jpmqBBSldtQnlorsRCXjvHinHM36gKd8K+UAd+eYZHQapkjhb4qcRHh7aks8Ye8a4tN0YWZT6BQLCgM0Fkg08nxchYuKOL3tskWCu15m+Uz4+kIAyjVj/qs7ukq83tHOayJ4GaKeu7WrGl22gVroOwFvrfTFnAvoGMWRAravj+AwgFCKWgkuMTsjkQtNkCLveBE0OwkMXC8bTZuBSCuv1A8P1ptSXHz9yO51tkEuUqIoCwb7sEknMWY4vhd9Rb3mUHIHGvgtKvM7XMrza0hIpV3pYlmKtawx3qD67lduHB2qEtetM/oQPWA4YMt9fOikIEzgXqSaR/c5CwvgXRMoTw==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=cisco.com; dmarc=pass action=none header.from=cisco.com; dkim=pass header.d=cisco.com; arc=none
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=FhA4F6oxPvGaR8J5wSYR41jl3dq0xbF0vN5gQ1bUULQ=; b=twVVrepvkyBowsce2Wn+sUIwGNyF+ko21AUQschqV78yVK1N8Spvdy4UQWIbM/Q7mQ+6SfmENOrhoeK+Y3pReL4lWNJ6oIGZYdjS7K3Sa4QGS/3uKTVxTwo/IyR9iuJv21HxG4dvZThvhi9RivcWSOIK6++OtEYy0YO/yiK+IRQ=
Received: from MN2PR11MB4366.namprd11.prod.outlook.com (2603:10b6:208:190::17) by MN2PR11MB3775.namprd11.prod.outlook.com (2603:10b6:208:f7::10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2878.15; Wed, 1 Apr 2020 15:05:42 +0000
Received: from MN2PR11MB4366.namprd11.prod.outlook.com ([fe80::3:2164:a8e2:33b3]) by MN2PR11MB4366.namprd11.prod.outlook.com ([fe80::3:2164:a8e2:33b3%5]) with mapi id 15.20.2856.019; Wed, 1 Apr 2020 15:05:42 +0000
From: "Rob Wilton (rwilton)" <rwilton@cisco.com>
To: Kent Watsen <kent+ietf@watsen.net>
CC: Andy Bierman <andy@yumaworks.com>, =?utf-8?B?TWFydGluIEJqw7Zya2x1bmQ=?= <mbj+ietf@4668.se>, "netmod@ietf.org" <netmod@ietf.org>
Thread-Topic: [netmod] All IETF YANG modules MUST include revision-label statements
Thread-Index: AQHWBryXXEWOVM1ZWkW+qvBAGEwM/Khhcj8AgAAIq4CAARsOMIAAQQwAgAF+90A=
Date: Wed, 1 Apr 2020 15:05:42 +0000
Message-ID: <MN2PR11MB4366F4A31584AC3C3A7F782CB5C90@MN2PR11MB4366.namprd11.prod.outlook.com>
References: <75CFDBD9-143C-407A-B7C3-26CEC51E229C@cisco.com> <20200328.094121.1160081114435152145.id@4668.se> <76623C79-BB91-4B5F-8FEA-406ADEAD1647@cisco.com> <20200330.202016.930329343788112268.id@4668.se> <CABCOCHS=y8d00xHLzV+LNpvN_=jScw5VizGYWXGopsQAi8qZUw@mail.gmail.com> <MN2PR11MB4366775C8E9A5488D33E484EB5C80@MN2PR11MB4366.namprd11.prod.outlook.com> <01000171313d4b26-a5e29676-2bd1-4bd0-9598-d3eee7fbf32d-000000@email.amazonses.com>
In-Reply-To: <01000171313d4b26-a5e29676-2bd1-4bd0-9598-d3eee7fbf32d-000000@email.amazonses.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
authentication-results: spf=none (sender IP is ) smtp.mailfrom=rwilton@cisco.com;
x-originating-ip: [82.15.79.32]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 12bbebfd-7cc9-4737-42d0-08d7d64e25d5
x-ms-traffictypediagnostic: MN2PR11MB3775:
x-microsoft-antispam-prvs: <MN2PR11MB3775E9DCD214A976F1B48C74B5C90@MN2PR11MB3775.namprd11.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:7691;
x-forefront-prvs: 03607C04F0
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:MN2PR11MB4366.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFTY:; SFS:(10009020)(4636009)(346002)(136003)(366004)(396003)(376002)(39860400002)(86362001)(478600001)(9686003)(66574012)(4326008)(186003)(2906002)(26005)(55016002)(81156014)(81166006)(8936002)(8676002)(66946007)(66556008)(64756008)(66446008)(76116006)(316002)(66476007)(54906003)(33656002)(7696005)(71200400001)(52536014)(53546011)(6506007)(5660300002); DIR:OUT; SFP:1101;
received-spf: None (protection.outlook.com: cisco.com does not designate permitted sender hosts)
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: fVHA8W6YwKWy1jnEghSruRrEP+IjCe6A2rLHkZ6kl3P01kVdXyJ+Lkv1iOEX9Y+mUgfU+0fktVIbnOHgIpRroa5gBGv4Kg8DDeljoJpQ5mrrmd2cjXDL9bzA7uS+n0IRNisgHJ7RFDgXwYyIGRjx9OUGdH/lI4vPDJLZbnJPGXfm3YDxyEjOIetQcUTYkFuST+mGtirJSxzSP8yvaGltyvbgj9tYh/D7eEfEAatMdIN28Elomt9Wvh1adgXhkvxgcJd/FegjBT2tFGzDtolSbrYcn0fdKitB4Q8jfAh41q6nbdgKsZR6GmVNHNIktbKAfJpw9zKfN+W4oCwrcQHXbDiydNKoYRvMEHxFxi4WmsS1qlwCNE2pGdlHHn0eb8LODPNZFxROzK/391aZTuqOIIyOLMztThfaY625HdtIJoTyaQSvSVIkp/h1VIG43MGI
x-ms-exchange-antispam-messagedata: vD8h0zmDrZlgRidFwPbfp9p1pgt6A5X4pBiS7/GEk14ttVyHTIvV6DujDIV1PN64Rq2z+RETaP2OXkMenmrskFiwWc7iBV74dE0oy69BLefvEkqe+RG/bdDRIwTlFlcL62TphUFfryoZaEBmEkip1w==
x-ms-exchange-transport-forked: True
Content-Type: multipart/alternative; boundary="_000_MN2PR11MB4366F4A31584AC3C3A7F782CB5C90MN2PR11MB4366namp_"
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-Network-Message-Id: 12bbebfd-7cc9-4737-42d0-08d7d64e25d5
X-MS-Exchange-CrossTenant-originalarrivaltime: 01 Apr 2020 15:05:42.3452 (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: 0AOtaqCgagUvtzZfLlcR5z/WA4Q0vy6dzy5fLO/+kmxtq+LY5w5ul+Zy7DZpBeTXnnHXCNh9qstpAJJ9vGrcaQ==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR11MB3775
X-OriginatorOrg: cisco.com
X-Outbound-SMTP-Client: 173.37.102.13, xch-rcd-003.cisco.com
X-Outbound-Node: alln-core-2.cisco.com
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/kFaLXMREBulC_7tfnHgWNOBouIA>
Subject: Re: [netmod] All IETF YANG modules MUST include revision-label statements
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 01 Apr 2020 15:05:50 -0000

[As a contributor]

Hi Kent,

Please see [RW] inline

From: Kent Watsen <kent+ietf@watsen.net>
Sent: 31 March 2020 16:37
To: Rob Wilton (rwilton) <rwilton@cisco.com>
Cc: Andy Bierman <andy@yumaworks.com>om>; Martin Björklund <mbj+ietf@4668.se>se>; netmod@ietf.org
Subject: Re: [netmod] All IETF YANG modules MUST include revision-label statements

[replying to Reshad as well]

Hi Rob,


My impression is that Semver 2.0.0 works fine if you can always force clients to move to the latest version of the API whenever any bugfixes are made to the API (whether they are BC or NBC).  This is a natural fit for open source projects, but not so great for long life paid support contracts.

Agreed.



The goal of YANG semver is not to facilitate release branching.  It is to allow vendors to fix YANG modules without forcing clients to update to the latest version of that YANG module (which may contain other unrelated NBC changes and have lots of dependencies on other modules).

This is what Reshad was pointing to as well.  I’m very familiar with the issue, from my Juniper days, where there were all sorts of patch and (gasp) customer special releases, either of which could introduce any number of NBCs.

The background, of course, is that [very important] customers have working/validated infrastructure running a specific release and simply cannot tolerate any change beyond the very specific one they need *NOW*

I get it, truly,  but I feel that the ‘m’ / ‘M’ suffixes are both inconsistent with general understanding and insufficiently to express what is needed.
[RW]
The aim is for the ‘m’/’M’ suffix to provide a mechanism to describe where the module has deviated from the rules in a limited way.

The hope/intention is that these should be avoided whenever possible, i.e. they are designed to be limited in what they can express to encourage regular semver and a non-branched revision history.

As YANG APIs become more mature, and as automation becomes more important, then I would expect that these APIs become more hardened, and there should be less usage of the suffix.



A possible fix might be to allow for <major>.<minor>.<patch>[-<anystring>], thereby enabling vendors to encode any format off a base release…and rely on inspection of the “revision” history indicate if/when NBC changes occurred.
[RW]
But this would look like a valid semver 2.0.0 (rule 10), but presumably one that is not following the semver 2.0.0 rules.  I also don’t see how having each vendor design their own scheme really helps interop.

I agree that one option is to tell everyone to look at the revision dates and revision history.  But I think for most people a semantic version number is much easier to mentally process than a date.


But then I question (again) the need for the simplified format at all, as opposed to just using revision dates.  For instance, if <anysting> represents a long history of NBCs, that they were based on some source M.m.p starts to lose relevance.

Is the expectation that the vendor's module versions will use <major>.<minor>.<patch> values mimicking their release numbers?  For instance, would FooBar OS version 20.1.2 implement YANG module "foobar@20.1.2<mailto:foobar@20.1.2>”?
[RW]
No, the plan would be to given the modules semantic version numbers that are not tied to release, i.e. the API is versioned independently.


   I can see product mangers pushing for this, but then are companies (like Juniper) that use alternate release name-formatting strategies disadvantaged?  How is that fair?   To thwart this, would the WG be willing to assert that the history MUST start at 0.0.0 and MUST only monotonically increment values?
[RW]
The solution allows allows any revision label to be used.  E.g. if you wanted to label it after release then you could call it “r20.1.2”, the ‘r’ prefix stops it being parsed as semantic version number.

So the choices that the drafts currently present are:

1)      Modules can just use revision dates if they wish.

2)      Modules can use YANG Semver, noting that all Semver 2.0.0 versions are valid YANG Semver versions with the same semantic meaning.

3)      Modules can use whatever revision label/scheme that they like, as long as it doesn’t conform to the regex for a YANG semantic version number.  This rule is only currently there to avoid requiring a separate statement to define the versioning scheme.  The YANG Semver draft could also define a statement to indicate that the YANG Semver scheme is being used, and then that restriction would go away.



Note that OpenConfig also hit this problem, but they proposed a different solution.  I.e. ship the base module with another module that contains deviations to fix any bugs in the base module.  Alas this completely decouples the real module history from any revision-date/version number contained in the module, since to really understand the version of the module you also need to know the set of associated patch modules containing any deviations to the base module.

I’d need to see an illustration of this to be sure I understand, but my first impression is that it is yet another attempt to fit a square into a circle.
[RW]
Yes, it is an attempt to pretend that Semver 2.0.0 is sufficient except when it isn’t.

At the end of day, we could just standardize using regular Semver 2.0.0.  But when push comes to shove, and that customer is demanding a fix, I doubt many vendors will say “no, I’m sorry, but our versioning scheme prevents us from providing you a fix”, instead my supposition is that most vendors will provide the fix, and just break the rules, probably labelling it a patch release (e.g. going from 1.0.0 to 1.0.1 if 1.1.0 had already been used).  In this scenario it is better to have a scheme that vendors don’t actually follow, or is it better to have a slightly ugly scheme that does at least truly express that a non patch change has occurred (i.e. going 1.0.1m)?

In the end, I see no substitute to relying on “revision” history which 1) perfectly tracks branching history and can flag if/when NBC changes occurred.

[RW]
I think that both are useful/required.

If the client is doing a large upgrade between releases then I think that you need to rely on tooling that compares and reports the exact differences between the schema.

But I still think that semantic version numbers give helpful easier to understand information for humans.  E.g. I personally find it easier to remember that the first version of ietf-types.yang is 1.0.0 (RFC 6021), the second version (RFC 6991) is 1.1.0, the third version will be 1.2.0 (rfc6991bis), rather than trying to remember the revision dates AND knowing whether or not any NBC changes have been made between the definitions.  I don’t argue that YANG semver is perfect, but I do still believe that it is better than all of the alternatives.

As a corollary to this point, I note that a lot more software artifacts tend to use explicit version labels rather than revision dates.  I presume that this is the case because most people find them easier to deal with.

Regards,
Rob


Kent // contributor