Re: Yangdoctors early review of draft-ietf-rtgwg-policy-model-09

Yingzhen Qu <yingzhen.qu@futurewei.com> Wed, 27 May 2020 20:37 UTC

Return-Path: <yingzhen.qu@futurewei.com>
X-Original-To: rtgwg@ietfa.amsl.com
Delivered-To: rtgwg@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 88EB13A0CA6; Wed, 27 May 2020 13:37:18 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.989
X-Spam-Level:
X-Spam-Status: No, score=-1.989 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, HTTPS_HTTP_MISMATCH=0.1, RCVD_IN_MSPIKE_H2=-0.001, T_SPF_PERMERROR=0.01, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=futurewei.com
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 CZY_nKCUBusd; Wed, 27 May 2020 13:37:15 -0700 (PDT)
Received: from NAM11-CO1-obe.outbound.protection.outlook.com (mail-co1nam11on2119.outbound.protection.outlook.com [40.107.220.119]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id C78AE3A0CC4; Wed, 27 May 2020 13:36:54 -0700 (PDT)
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Q8NnWb7zrHZcwt3f1+0n1lFed75oMC1X5J1aJK6PFDvAtNQctEJtolqn2cEJVAgdKZhV2XHAcPUy/ICIeNuXkQcC/XpyOvKVDBW+LILfdrQASbwMxG0DaWgiDwE4IWooe+y0PlbWWaSpadTAi8yHKPiBmbFVMqqievBGwuU5qAJWD3j/ks3jTCA+o4AYPjdKo2bLvmW7YT1Pj1aZJsDxIF8FpyxCmM3ZjjOdg1WHMQe9BB3jxEp/SlYYNYacyAyXY60uMJYDSfvaM0/LTI1b1ZeFHxbbnbm1E1E1cG5G1VBYxyJk7OSSi+p1+bc0fsItYim1Xnsy23xk916gjz0ssg==
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=rIaETV91Ccgd4AKl7EQhNb0vumfhAKexLPV7OocIo7k=; b=NPtx5GVasRUmbp03MxdBWY3RGDvcvT1oc/WO+oJ8mYjs0hlCRJFbMMNQgA6viB4uaQrS/KLYtSLUOYVYxlT1HEkvY+hdSjLlQaT/Qawsuy7+C0dJH7T0joVvr/2KKnQNmhsavxrsl/AI3V//PqjrYgW64+GLyeAUta9bphalJ1+GtIiKIt+VZbEm5NpZmRZ+9CptQULuAXdRlesV+wF6TSFjK8LA/SOKLds0rhAV4AibXILALdyvObtHtBeTMNVW1fdv1RpBO4XihBT9VdUp8SGfdh/o+DyzzxS3jKaBPQWiL5ba73wFYXjIDqKZEPCBuHX6I98qIYaYgyxK7tqNxQ==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=futurewei.com; dmarc=pass action=none header.from=futurewei.com; dkim=pass header.d=futurewei.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=Futurewei.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=rIaETV91Ccgd4AKl7EQhNb0vumfhAKexLPV7OocIo7k=; b=ViIRDeV7ESrk+t+iZHpGSvxobLRjKcx98dzA+t+toxLnp3fGeoYzlZGfVGzVOYYsxkTJAcaehxHjwj4kwB0zphW7lAN8b742Ilbn49j3MHY8XDAhd37jr5zagrRF7boDA0FLjmWshJzMt/X/pj2k2jq3Xof6w2z87I5VZA9A20M=
Received: from BY5PR13MB3048.namprd13.prod.outlook.com (2603:10b6:a03:188::21) by BY5PR13MB3523.namprd13.prod.outlook.com (2603:10b6:a03:1ae::27) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3045.9; Wed, 27 May 2020 20:36:52 +0000
Received: from BY5PR13MB3048.namprd13.prod.outlook.com ([fe80::28f0:8a33:3418:b39b]) by BY5PR13MB3048.namprd13.prod.outlook.com ([fe80::28f0:8a33:3418:b39b%4]) with mapi id 15.20.3045.014; Wed, 27 May 2020 20:36:51 +0000
From: Yingzhen Qu <yingzhen.qu@futurewei.com>
To: Mahesh Jethanandani <mjethanandani@gmail.com>
CC: "yang-doctors@ietf.org" <yang-doctors@ietf.org>, "draft-ietf-rtgwg-policy-model.all@ietf.org" <draft-ietf-rtgwg-policy-model.all@ietf.org>, "rtgwg@ietf.org" <rtgwg@ietf.org>
Subject: Re: Yangdoctors early review of draft-ietf-rtgwg-policy-model-09
Thread-Topic: Yangdoctors early review of draft-ietf-rtgwg-policy-model-09
Thread-Index: AQHWLmaRqyIyvvjQ2kuvlHXV5sAvRKi1rUYAgAHrL4CABGJ9AA==
Date: Wed, 27 May 2020 20:36:51 +0000
Message-ID: <035C70FF-D60E-4269-A8EE-582D139C2A4C@futurewei.com>
References: <158995210745.32133.15039309101330577713@ietfa.amsl.com> <2735CC19-B499-468A-9B31-C8F9D57802F2@futurewei.com> <B5D48696-88FC-4BF6-9B2E-3BF556520D58@gmail.com>
In-Reply-To: <B5D48696-88FC-4BF6-9B2E-3BF556520D58@gmail.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
user-agent: Microsoft-MacOutlook/10.1e.0.191013
authentication-results: gmail.com; dkim=none (message not signed) header.d=none;gmail.com; dmarc=none action=none header.from=futurewei.com;
x-originating-ip: [2601:646:9500:c900:5cfd:9078:1476:82e1]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 0b09bc95-950e-46c3-7097-08d8027dafe7
x-ms-traffictypediagnostic: BY5PR13MB3523:
x-microsoft-antispam-prvs: <BY5PR13MB35231513CED5F14500919E2DE1B10@BY5PR13MB3523.namprd13.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:9508;
x-forefront-prvs: 04163EF38A
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: 6SS2ScaPgoJCVnUYNehph08Pj0aMXcg7bssxBH7mBz3hEmtAouRwurHAK8VIhZfDxbPDia2170Mm0lKydA1au1tEXb0jBDDwTXOkP3G+TdzwrxAhhGsSSufvP1wVOJj9CZBY/LoG4RTFeFjl+Ib5Qza6WSv2Iatg+Pvm3dAKGzJGL963maFguqYvE0adHigMAEf7HK0dRkeMmbrZjwvniKaNnRHoNetz6DLcdMCa/40u/D3KOnV1glLJxz/XG4FNSg6HZeFlO4Cd/4AuUdTt9VRCeuNC+H2UczdqMJKXm9jL5w0AjnCvT0yiPvjX5UK91Mjra5C2xk9eyjkAec48Ubd+syRLDv2XT97Ngdl166p4+HHPzKim4KMFQ/a8u6M7DKhds3Iswn63gRtwPkE8MA==
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:BY5PR13MB3048.namprd13.prod.outlook.com; PTR:; CAT:NONE; SFTY:; SFS:(4636009)(136003)(376002)(366004)(396003)(346002)(39850400004)(66446008)(76116006)(64756008)(966005)(6512007)(66946007)(66476007)(6916009)(71200400001)(4326008)(8676002)(54906003)(8936002)(53546011)(9326002)(316002)(6506007)(186003)(6486002)(2906002)(33656002)(44832011)(66556008)(478600001)(5660300002)(86362001)(166002)(36756003)(83380400001)(2616005); DIR:OUT; SFP:1102;
x-ms-exchange-antispam-messagedata: 3BBN+xgdZGBCtfhtwwfIBVQKbvEuQ7itSQRv/yj22essjAKH3Juofjv4pxehyq+07CJv7VUBNhc8msRUhnzTRavw1V5B4IOWGsU3TySb9DC/l4L/izwAFH/FuPixDnfLqQTnvV9WZvn3Cot//ZwUtgIgijGlIZ49BDWhAS0qphLyI06PBNgKGbQ2YWpJ0GhKh+KMzR9IecMg507K7f3Q2FXVErbzle1+3qdaP4C75nXPF2hlWRjpFv/DSBAQhZpOPiOR+IyXyvudCcaitUMl690Mq6vavtRjtddfSTrVXQMA08owqPKe184QewLZJrGAWSh1R7Th26EpHTKtBo4D5oHOzTytzZpAYcR+D+WkA5yab5owhq+hb6fKdcXYcVQl0XZhY5uwtQeqbWsvQMOks1agahj6keZKwsJRKNOzkfX94o1OB1U3B3xjXMMWgIRIvjdvmz/qEpl5xFmgyRO8opOarYnph+pkXXwZbhfzquFgLDmh2HeaGdCl0KPlq94fdgJesOJDMd6ctE/30EmUSbuhvyMXTL4XgZLlSJD495UCn9Wmqvtc6kEtu9gyo9tG
x-ms-exchange-transport-forked: True
Content-Type: multipart/alternative; boundary="_000_035C70FFD60E4269A8EE582D139C2A4Cfutureweicom_"
MIME-Version: 1.0
X-OriginatorOrg: Futurewei.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 0b09bc95-950e-46c3-7097-08d8027dafe7
X-MS-Exchange-CrossTenant-originalarrivaltime: 27 May 2020 20:36:51.6854 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 0fee8ff2-a3b2-4018-9c75-3a1d5591fedc
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: jhOxNhY3aT+qw93TUt40w+hqfQqzoWpgU64oTSKlX12j3Z+A1NDYG84NTguy3Qdx/BqPFKa/5x9fy7qmYMAKQQ==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY5PR13MB3523
Archived-At: <https://mailarchive.ietf.org/arch/msg/rtgwg/opxuc04qKKnrgw_b4YAQvQMN35g>
X-BeenThere: rtgwg@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Routing Area Working Group <rtgwg.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/rtgwg>, <mailto:rtgwg-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/rtgwg/>
List-Post: <mailto:rtgwg@ietf.org>
List-Help: <mailto:rtgwg-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/rtgwg>, <mailto:rtgwg-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 27 May 2020 20:37:24 -0000

Hi Mahesh,

Thanks for your nice and patient review. I’ve uploaded version -11 to address your comments.

Major changes:

  *   Removed groupings only used in the model and not meant to be used later by augmentations
  *   Added an xml example in section 11.
  *   Fixed the cross-reference issue.
  *   Changed the “mailto” in the model to “Email”



Looking at the terms we have so far in section 2, I don’t think it’s necessary to add a definition for “routing policy”. But this is open for discussion.



Thanks,

Yingzhen

From: Mahesh Jethanandani <mjethanandani@gmail.com>
Date: Sunday, May 24, 2020 at 11:39 AM
To: Yingzhen Qu <yingzhen.qu@futurewei.com>
Cc: "yang-doctors@ietf.org" <yang-doctors@ietf.org>, "draft-ietf-rtgwg-policy-model.all@ietf.org" <draft-ietf-rtgwg-policy-model.all@ietf.org>, "rtgwg@ietf.org" <rtgwg@ietf.org>
Subject: Re: Yangdoctors early review of draft-ietf-rtgwg-policy-model-09

[Trimming the list to open issues]

Hi Yingzhen,


On May 23, 2020, at 1:21 PM, Yingzhen Qu <yingzhen.qu@futurewei.com<mailto:yingzhen.qu@futurewei.com>> wrote:

Hi Mahesh,

Thanks for the review, very much appreciated.

I submitted -10 version to address your comments: https://datatracker.ietf.org/doc/draft-ietf-rtgwg-policy-model/<https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdatatracker.ietf.org%2Fdoc%2Fdraft-ietf-rtgwg-policy-model%2F&data=02%7C01%7Cyingzhen.qu%40futurewei.com%7Cc70b253b70a247ec74aa08d80011ce8c%7C0fee8ff2a3b240189c753a1d5591fedc%7C1%7C0%7C637259423777478171&sdata=ZN3wyJ8RziT2DBS7WCNgiffg8yDO25jMSrPcMF4TDlM%3D&reserved=0>

Note: There are YANG validation errors because yanglint can't find model "ietf-if-extensions", not sure why.
yanglint SO 1.6.7: yanglint --verbose -p {rfclib} -p {draftlib} -p {tmplib} {model} -i:
err : Data model "ietf-if-extensions" not found.
err : Importing "ietf-if-extensions" module into "ietf-routing-policy" failed.
err : Module "ietf-routing-policy" parsing failed.

ietf-if-extensions is part of the draft-ietf-netmod-inft-ext-yang draft, which is still a draft. It should ideally be in the {draftlib} path variable. I would suggest a open an issue with the tools team to have them track it.

I am assuming of course that you are able to validate the model locally on your machine.
…


   The document includes a section on Terminology and Notation. However it does
   not define what is a "routing policy" or provide a reference to it.
[YQ]: I'm not sure there is a standard definition of "routing policy". I'll do some
research on this and see whether we should add it to the terminology.

Looking at how the draft describes it, how about something like this?

“A routing policy defines whether a routing protocol imports a route into the routing table, modifies it, or exports a route from the routing table."

…


   Section 10.1 - Routing policy model

   The model uses a lot of groupings, most of them used only once in the model.
   That makes the model difficult to understand. Unless these groupings are meant
   for use by other models, they should be folded into the main container. Take
   this grouping for example:

        grouping policy-definitions {
          description
            "This grouping provides policy definitions";

          leaf name {
            type string;
            description
              "Name of the top-level policy definition -- this name
              is used in references to the current policy";
          }
        }

   For one the description of the grouping is not correct. Secondly, it is used
   only once in the model and that too to define a key of a list.

[YQ]: This model was initiated by OpenConfig, we've removed some groupings
Since this become an IETF draft. I removed "policy-definitions" and "policy-statements"
groups.

The general rule is that if the grouping is used only once in the model, and not meant for use outside the module, that it should not be a grouping.

For example, ‘grouping neighbor-set’ is used only once in the model, and I doubt it is meant for use outside of this module. That grouping should be collapsed into the model where it gets used. Same for ‘grouping tag-set’. These are just two examples. There are many more.



   The YANG model imports multiple models from other drafts. It provides normative
   references to the imported models in Section 2.2. (A nit here is that it
   missing the cross-reference in the table for if-l3-vlan),

A nit. if-l3-vlan is still missing the cross-reference (and the hyperlink) to the draft. Also why idnits is giving you an error at the bottom.


but does not provide
   references to them in the model. See Section 3.9 of RFC 8407. Please add
   something like this in the model.

   import ietf-inet-types {
     prefix "inet";
     reference
       "RFC 6991: Common YANG Data Types.";
   }
[YQ]: fixed.

   Please drop <mailto:....> and just keep the e-mail address. That tag works only
   when embedded within a HTML document.
[YQ]: do you mean the "editor" in the model?

I meant to say you should drop the word “mailto:" from the list of e-mail addresses of the editors. That tag works inside a HTML document, not inside a YANG model.



   A pyang compilation of the model with —ietf and —lint option was clean.
   However, there seems to be an issue with the example in Section 11. Instead of
   actually including an example, it is showing the path to what should have been
   the example. I was therefore not able to validate the example against the model.
[YQ]: I can't find this example in OpenConfig Github anymore, so removed this section.

Hmm. That leaves the model without any examples, and examples are important.

I was able to find the example in an earlier version of your own draft (01). I would suggest that you take that example and modify it to make it compatible with the latest version of the model. If you need help, let me know.



     Checking references for intended status: Proposed Standard
     ----------------------------------------------------------------------------

        (See RFCs 3967 and 4897 for information about using normative references
        to lower-maturity documents in RFCs)

     == Unused Reference: 'I-D.ietf-netmod-sub-intf-vlan-model' is defined on
        line 1620, but no explicit reference was found in the text

The reason you are getting this error is because you are lacking a normative reference to I-D.ietf-netmod-sub-intf-vlan-model in the document. Goes back to the nit I point up earlier.

I would suggest that once you have fixed all the issues in the draft, that you re-run idnits locally on the machine.



     -- No information found for draft-ietf-netmod-intf-ext-yang - is the name
        correct?

     -- Possible downref: Normative reference to a draft: ref.
        'I-D.ietf-netmod-intf-ext-yang'

     -- No information found for draft-ietf-netmod-sub-intf-vlan-model - is the
        name correct?

     -- Possible downref: Normative reference to a draft: ref.
        'I-D.ietf-netmod-sub-intf-vlan-model'

[YQ]: there is dependency on both 'I-D.ietf-netmod-intf-ext-yang' and 'I-D.ietf-netmod-sub-intf-vlan-model'.

        Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 5 comments (--).