Re: [netmod] rfc 6087bis - stress importance of instance examples

Phil Shafer <phil@juniper.net> Fri, 03 March 2017 20:09 UTC

Return-Path: <phil@juniper.net>
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 09AD9129543 for <netmod@ietfa.amsl.com>; Fri, 3 Mar 2017 12:09:22 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.902
X-Spam-Level:
X-Spam-Status: No, score=-1.902 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=junipernetworks.onmicrosoft.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 saPzhR19s27o for <netmod@ietfa.amsl.com>; Fri, 3 Mar 2017 12:09:20 -0800 (PST)
Received: from NAM01-SN1-obe.outbound.protection.outlook.com (mail-sn1nam01on0104.outbound.protection.outlook.com [104.47.32.104]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 1DCA7126BF7 for <netmod@ietf.org>; Fri, 3 Mar 2017 12:09:19 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=junipernetworks.onmicrosoft.com; s=selector1-juniper-net; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=OA9MvsfaiRckf9a2NHgoAN70X2Muw3ykbhsKrTJ/vvA=; b=aw3RiRghMMEXD7B+IQNX6qvFuHTdA1TqNEVdTWEQtPECVUufL/fJG/Z9I6XpjUrx7pFBfa5H6/XRV1zcT7QJFh96S0av1/kxjJShmkQ1/sWadLpUPl+mTm8BJTw3+kqI2cENJ+7Gxw22Vz7qXdItlcb/zlULFpfDuUp/9+05oe0=
Received: from CO2PR05CA044.namprd05.prod.outlook.com (10.141.241.172) by BY2PR0501MB2006.namprd05.prod.outlook.com (10.163.197.17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P384) id 15.1.947.2; Fri, 3 Mar 2017 20:09:18 +0000
Received: from BN1BFFO11OLC001.protection.gbl (2a01:111:f400:7c10::1:140) by CO2PR05CA044.outlook.office365.com (2a01:111:e400:1429::44) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.961.8 via Frontend Transport; Fri, 3 Mar 2017 20:09:18 +0000
Authentication-Results: spf=softfail (sender IP is 66.129.239.18) smtp.mailfrom=juniper.net; ietf.org; dkim=none (message not signed) header.d=none;ietf.org; dmarc=none action=none header.from=juniper.net;
Received-SPF: SoftFail (protection.outlook.com: domain of transitioning juniper.net discourages use of 66.129.239.18 as permitted sender)
Received: from p-emfe01a-sac.jnpr.net (66.129.239.18) by BN1BFFO11OLC001.mail.protection.outlook.com (10.58.145.12) with Microsoft SMTP Server (version=TLS1_0, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA_P384) id 15.1.947.7 via Frontend Transport; Fri, 3 Mar 2017 20:09:17 +0000
Received: from p-mailhub01.juniper.net (10.160.2.17) by p-emfe01a-sac.jnpr.net (172.24.192.21) with Microsoft SMTP Server (TLS) id 14.3.123.3; Fri, 3 Mar 2017 12:09:16 -0800
Received: from idle.juniper.net (idleski.juniper.net [172.25.4.26]) by p-mailhub01.juniper.net (8.14.4/8.11.3) with ESMTP id v23K9EY4030165; Fri, 3 Mar 2017 12:09:15 -0800 (envelope-from phil@juniper.net)
Received: from idle.juniper.net (localhost [127.0.0.1]) by idle.juniper.net (8.14.4/8.14.3) with ESMTP id v23K5AAe059307; Fri, 3 Mar 2017 15:05:11 -0500 (EST) (envelope-from phil@idle.juniper.net)
Message-ID: <201703032005.v23K5AAe059307@idle.juniper.net>
To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
In-Reply-To: <20170303191348.GA3570@elstar.local>
Date: Fri, 3 Mar 2017 15:05:10 -0500
From: Phil Shafer <phil@juniper.net>
MIME-Version: 1.0
Content-Type: text/plain
X-EOPAttributedMessage: 0
X-MS-Office365-Filtering-HT: Tenant
X-Forefront-Antispam-Report: CIP:66.129.239.18; IPV:NLI; CTRY:US; EFV:NLI; SFV:NSPM; SFS:(10019020)(6009001)(7916002)(39450400003)(39840400002)(39860400002)(39850400002)(39410400002)(2980300002)(189002)(199003)(9170700003)(106466001)(105596002)(7696004)(189998001)(92566002)(86362001)(6916009)(2950100002)(5660300001)(4326008)(8936002)(6246003)(81166006)(8676002)(7126002)(2810700001)(53936002)(38730400002)(110136004)(5003940100001)(229853002)(356003)(626004)(2906002)(50466002)(48376002)(8276002)(305945005)(47776003)(6306002)(77096006)(53416004)(50986999)(54356999)(1076002)(76506005); DIR:OUT; SFP:1102; SCL:1; SRVR:BY2PR0501MB2006; H:p-emfe01a-sac.jnpr.net; FPR:; SPF:SoftFail; MLV:sfv; MX:1; A:1; LANG:en;
X-Microsoft-Exchange-Diagnostics: 1; BN1BFFO11OLC001; 1:kHn9nmKprePhC0azSvVXl7vcvWVcePTdVgNNnHgiUPtJULFxznHf3qOoH+3EFehIQDN+ZZBZs3+uwnvbdWyZwchjt037wxlUk84ZIytmuIx6MmJ4ztTil+VZD8tv5rQSkkWxxLJ8S9u2s3wfYiv02frn+GX209JGz+Pe96y7qhiVOHCagzt/X7frq5eYuEYRObiK8AQeIQJSYspq3Kig/7MmsofQCp49jsUV01mV687C28eGH5RudxGrx8wKLOswVyR9OhlFFUTNgFj7uF1CvwpNar0cWdnWd4u35UXFBhRx8iXaFrFOYFRulLiXUunyCqQSuQW1DB670vZ2bm226vdRFu1MvMdMna2fNahBMUIwm/iJCOKYpLyQAKIyiTxxsVyaxPwofiH+/jw2RRdQc/iu6ChAmOWzhTUFEVxqUAA0be+8w8xgbYdmH21MXnXkNGMJtFnJlX34nw5Y1C0GXuejMEfKWH5+JilMZqi3dySiQr9UC7Y5j/EZoazLzbjmK0GtMVg1VaHc6nsNOpaiajhqNEerW5avgT6z0/A+Nqx9hSaWN5VRvA8YUcmam1wEnsO7v/JIh2Qmj+1H7wmm+w==
X-MS-Office365-Filtering-Correlation-Id: 4709dd97-890f-41f8-9eeb-08d462712bfd
X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(22001); SRVR:BY2PR0501MB2006;
X-Microsoft-Exchange-Diagnostics: 1; BY2PR0501MB2006; 3:GCemALFMrABhH8yijUbDrj7GjWEno+qXxspbcxEYticaDH8m4XAB3MjZ2jun1tlsMtd1MFA/OwA2yRfquhR8bVNkq3BL+qOwfZGNdP+E1WuTw0acLZ9EMhU2c3s+J2SAg1FWzKTd++W+yqy0JsEAjZEL0sxRzV0ZVyLMNJhzsOe2NGET/zVzpMykjn+GVqE0zr6FmM5cKt48BEH3xspUzXkuqH+VVlc7g8HY5jlbAMuN8cIAU7q1D0EB4CP2BOqy55ZvJWh4VZxlp5nR4Cu4MyO2EnB533bzjPP5cOF1VcZ0WumDOQX/rouOEN+vbf9rnXuX+8PjYbGLyLrU6zd1LEK8D8H0gQAoq+cHy3Qt1HuONVLfHAoQGpI24drGV5KD; 25:ofR+0MfnKx8oxBK478s29bgr13gRK9pnRDeQEn+cMFPnAoFlva4oyRq+FKCCo1qU+R5K4N4Tjia3D7iweH2VMhEXrD6gbWTKWJ0gKiTkKYtN9wGrExx8+7JTB3esg75guGdNr1Mfd2/42nwxrsAjYAkp5brimU2h96jRtvbAdA74trLPkEQtLksLOlNrYNoBd5HhubMLYqXTtb4czy1QrLWf1MfUMM1bFMQl3aoRc1vdXNuKUEnhn69qoKGL0ZlcJiSKxbVz+nI7BvY2d9PDrm+kijdk3tM1BvlDTpUB6iX6Ol5+uPelW+ehGOhAAH9aN+qn8MkBCtdy+lyDTZOoyZPGy9L4Tnjm9mUcWcBGQvspq45XIeH8ZGqD3xZubQq8SkqWquIAYGoLsIQ/yF4n7zl9B04MMxdky2lffjPnEwKopSh2qRKw11/PZuN6UK8rfSRKDGT3rj4+ynsHFOaClA==
X-Microsoft-Exchange-Diagnostics: 1; BY2PR0501MB2006; 31:dWspVg8JMqdekKbqmhGzSOJghSJzZslWTt9UIR9otbFGdx0uoh/J/k/lavm1h7huFpzRk6RAbFUhEWNtwd6ZNNS2SjqU8ISU9zHo+36Gk/+NSnpqEwozRNYUhz0Bf5CtvrUmHPExzs0zVfE8C3JVarlEHXZPvcetizz5YgmWyXNNhGrpng6hhQapbLoClEpiMIWNB9c6pmhBt09eMtOU/qeW5YbRLRFyVBZstD5p0j1JYwu8rRB6oIIUAiLf75j3ds5cC7KliQqXgeNs1SR4Vw==; 20:3k9oCo7NkwOcxjoZ8iquqEq6FjsUg4sDBwepQIyuwhPERj12v0+KAzLw7w35lBPrBbXZvNvbWG7UqNVYA4HOEaxLjzgU8pA6My0zxoRO58/lXfYqWwKwKEi5uiPCb9e+04jHpSN/h7AQ80m20mQ0oaLDRWOU9AhiAhEuZKj0S6tiNqSoy9LIBfZPD+mvZ6PLGLl+k/H/W6PvMyS7fKj1+eOJEM9wqdVQ8HPh9CYvAj5e88AW5ftsED2NcfKdNonwcQENEpOnzwSv/emCn53gr5y3QIt3xz37kH6gg7/I/6G2yh8LlTt8qf5tudTFRgQJdLWT3NTYPsXQzq1ckX2Y/p9gvniRbGT0hU83EDk4TmOleJ4uPb06tSiRQryFTdBJlYTD7LRBEql+BLydhJwDqasKmW7L2sF/1v4Fut+GF3fHLdIlu3GXd3NGtXo/epuAAXyq9mBW13ABCsZ93iZlPKY0NBaU0uTFMuurxl20UwjPEgwZdJCZvTRFaXbEfsqq
X-Microsoft-Antispam-PRVS: <BY2PR0501MB2006C2B97143216CEB5570C7C92B0@BY2PR0501MB2006.namprd05.prod.outlook.com>
X-Exchange-Antispam-Report-Test: UriScan:;
X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040375)(601004)(2401047)(13017025)(13015025)(13023025)(13024025)(13018025)(8121501046)(5005006)(3002001)(10201501046)(6055026)(6041248)(20161123555025)(20161123558025)(20161123560025)(20161123564025)(20161123562025)(6072148); SRVR:BY2PR0501MB2006; BCL:0; PCL:0; RULEID:; SRVR:BY2PR0501MB2006;
X-Microsoft-Exchange-Diagnostics: 1; BY2PR0501MB2006; 4:Tp35wiKQ/VzkfJLwrmEyHfFdqQTutgaMxGxebRxeNYbJNZt6Yut+wINC/NmM/P20LEzcaWQosdaNbH0JFjt4/O+dgMfWN9DPcXMh63WjmLe4PFji4KpRUQOlDl2tSBmRXYuG160IAgXyDKCnJiA3IsndR+Cfa8+RbDkmdSa/r4reY8zaKTwHBMYQvbyfUcqKXqXkrYgH1SU9VOKVUHz0yNkDM/DNHyM0f+8uCTBRl+f54cgvTSMotMopKxSRhXcGm5tOj2w+r4yRUs+O3wq1xAbRjy6oXnWHCFQCFqvcW8jsU90hmGJ47YeMJcRq0VG/lCO2RnTMqFIh+ALN28a3kjNgu2EZlql7EHiYNJqcJx/R0gFPLA/6CEkemBBx1oq7hGKx7OdcpDet7Dp3ZEankkzvm5L18Pc7V0a9hVpbI/dP8+9+Ao1YXSl62keC3ZdeTWdQoN0mzJTdk87DhpnZ1Vj5zxQ/YGNt4pu+5NusEBF9MbfVO0r7nSkSv95XfFMh+Hy7ZatA3+Rao0Jej360HsXC96owHkKwlEdaV/PbZEO93TdT7AoATL5FxA5RBKytHVri8kyV/8TGm5PWqarYolyNPqml2RwgNYQOAPDjCWk/OHqQ8mBwkohKz8c2xoRmXc8ylxs0EpjJXxgZFvo0dCPrCnWlPDr75/0rb5DCRFv5mMRouLPcQpIK4rF66pQ2OHoAF4eipGe9f4/wUjVgOw==
X-Forefront-PRVS: 0235CBE7D0
X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; BY2PR0501MB2006; 23:xtsVBuBeHaHKtLNcw+U4gCSyCsHD4YqMSETREMw?= =?us-ascii?Q?1K8UeQhqwA1BEQORLABNL+zuDGt7TQhcFWUUnHtmQd91rxp/g7PyqkOl7C5/?= =?us-ascii?Q?D1IEthtv4JyDu6Cm4wSU+bN47K171Q4Q6hNbnBw13fYYtAL1DjrYaAV2S9JZ?= =?us-ascii?Q?PbGEAypiPT9F+PRx01LCM3fUNh26XHYg8oIfo/48PAANvPg6VSKDH3EJg1yg?= =?us-ascii?Q?mfsY3oaaaVLAqeJYcc3uF6SgfMK79mbDPa+EGlB/Xq8j7jv5QQnn2U73t/aJ?= =?us-ascii?Q?k89FtvGd3YHzJLDyQ/cV5/iyBg+ymh2ebSlVFsw4VqXXdKbI56r+l8XBEECM?= =?us-ascii?Q?B7LOhYmJsMLLqrwfJZLPpFiIeRUmbjrOgowvopvnw3CA80rykC9/3HzMfmj7?= =?us-ascii?Q?28demOxSOLg2+hQ83ph0HI6qQmCaU2dT3Qar0Ss6GLyoGlVDoVCfD6yvSirT?= =?us-ascii?Q?bmGiyiwyq9DOLvgwB0+PH30uKBAV0m5zkaExx+hNaLbRorqJj8+JwUZJmDI8?= =?us-ascii?Q?ZUAXFTYPW2QaLlyc/eCHQ6qdr528BaUDx8vh9xrmMfrCGLXSW155n7c+pSZc?= =?us-ascii?Q?31ScXiDWarOlCdP5zc61Z2xBdQTgL/0A1AUcHaGG7ZY/FhUBYX+/cDVco6eE?= =?us-ascii?Q?L8iFVtZhI2RTSa6gJb3Rw1UdlDaQ1twO1Rig9GKpSlDhVPSxqvx7md5To28j?= =?us-ascii?Q?8dk++QYZYES2znww3s8YD5ENw5fH8lt/JNAqlsi90kOM+06cXH5uMTV6AHsO?= =?us-ascii?Q?ujGc/iu7kAhzUVjzLKfj1Fv7KijlOdac412/ui6dXRMZR7nmXNJcCpd2gqWy?= =?us-ascii?Q?SmmOj9HWjOTSMGUnKUQw/zF6/acUpCPG+a7xoxLx1hhFHhPcKt3GNqc/itDG?= =?us-ascii?Q?E+o9ErKqlXqlI0R97UOQqp9arcuYkt+yZpBHT0DoNnJuwrY8zrGIuLJVu4gg?= =?us-ascii?Q?/PtI+x3lG4IqKZatpEP3WXX5d4JY6xmFESgHcWRKn3WF0m1iaM/vuGNHQfHU?= =?us-ascii?Q?iIwYxT8Y8EOm+8C95yrAgs7XgyYjSfo1S6y6bdFo5abR80SDi4/Ga5vdVZCv?= =?us-ascii?Q?c/T/m1IeUCDiUUgwkw/nyGfFUmrOnyO2r7rSpDEXr4pFU3nvBM4i9Uacr64u?= =?us-ascii?Q?/MunMGr7HqUHcIEsdMC7uvGAyL10b08HArSDLQtv6BlV47ZlpNkG20Q=3D?= =?us-ascii?Q?=3D?=
X-Microsoft-Exchange-Diagnostics: 1; BY2PR0501MB2006; 6:JGOukzScC9B81wCH7+EHgKdHhkXJsSo6r0gF6EojPHONN6d4+0eIOzCABOdIfAURN0KRfUwe9SkA62dv0+41LSDLjMjSj0wCOS4dyNk569GOS4MMiC+44pNGvET5eIhKdfX5+pTupegSfOYo/oZUFQTmhW1Xy685Hb9GFX8TMHY5evgQ4/o6IzYqYzhKpGZOifqCEOhYgV4jdkp1ZdpYIZ43ago+hAQnHnsuP85MopWcd+dKSY6Z3TT6vA3HCwl8Z1miOKZpHIVR6esqfB2Kc4jpHLPdbc+deUM5WFwrLdMSu8seRx7pqepsqdIAmIpzhrxXFD636PrXO15jkiK2qVqLMOeALOSFYmFWQalexKUWPnr0VRu4p+g9LD12XUzKVPs/iJ/omfSc9fUhfcdVfUSaXeUgRimB4XGDLLo5ufU=; 5:zh+rD3YnRvt9n/O+b7jsfLUNqfO76iBAcuX3BYrHuRlTUjeoKlsUHb8fD85slpOBkFL63qRDo4+dRd10pfd16k/S5vNrY/sejJG3gCn81w+9gHNUeCwQw4MtWSLS1ki1oOUheXKI4vOfDencxbp+3w==; 24:N6Tf3edxgPHHaw96NDr2XLqAGdp6NeY0zucNmAtfOctfx+yT18WRh4mb2yxjzjw1loSsHl0Fi74+c/YTo7vrvqrhGvpmtSRT+UxQMiB7+Lo=
SpamDiagnosticOutput: 1:99
SpamDiagnosticMetadata: NSPM
X-Microsoft-Exchange-Diagnostics: 1; BY2PR0501MB2006; 7:xKMT7hAnEHkOuMBp+Y/RgzVv0U9rjqNjxXyrP8DQmwtbBE9oleneRTKaU+8R5B3aDIHyB1bsoEeI/c3TMbo6e+S4Lf0+F8Dzco1+vq4c/9jY6sf3NA4hlxwV5WWANFxZTttNG0t3ig3xVSKLQgaR6qFZCCmHFNAoBVCNr1r9z6htrxZWMpJtIEEBA7JCX3zhWKPy67Xu+/Lpq+0w+HQZOcmRUXGGxH6ZByekUzCR+EyBXD3GwVVAt6lAaQ5qs9hPosI/Yyj2kcIiftN1Eik7IZbRY83OItLPtIFXkOl0rIPQLAVgp5PWhtCdPb4GF0QkZL1U6oUBmYHKII9OF5Ed4A==
X-OriginatorOrg: juniper.net
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 03 Mar 2017 20:09:17.1362 (UTC)
X-MS-Exchange-CrossTenant-Id: bea78b3c-4cdb-4130-854a-1d193232e5f4
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=bea78b3c-4cdb-4130-854a-1d193232e5f4; Ip=[66.129.239.18]; Helo=[p-emfe01a-sac.jnpr.net]
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY2PR0501MB2006
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/GUQ2GKZal-FVQDneLagS8LBiSbU>
Cc: netmod@ietf.org
Subject: Re: [netmod] rfc 6087bis - stress importance of instance examples
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.17
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: Fri, 03 Mar 2017 20:09:22 -0000

+1.

As someone who does internal code review for Juniper changes, having
an example is a huge help to the reviewer (me).  It also helps to
convince the module author (them) that what they are advocating
will look horrible.

Thanks,
 Phil



Juergen Schoenwaelder writes:
>Hi,
>
>my experience is that when writing YANG modules it is tremendously
>helpful to focus on the instance documents. I find it essential to
>write down example snippets of instance documents to see whether they
>look elegant or clumsy. This is often not easy to determine from just
>reading a YANG model, in particular if groupings are involved. Examples
>help so much - you can easily spot whether the usage of singular or
>plural is reasonable in your names, whether you have redundancy in
>your names, whether the overall organization is effective. Even better,
>we have tools that can validate the examples so we can even be sure
>the examples are correct. (And if you do not know whether you got
>your pattern statement right, well, one way is to write examples.)
>
>I think we should encourage authors to write examples. It will help
>them to create better models and it will help reviewers tremendously
>while reviewing models. Good examples will also help users to get
>started.
>
>/js (who apparently is doing some heavy YANG reviewing work today)
>
>-- 
>Juergen Schoenwaelder           Jacobs University Bremen gGmbH
>Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
>Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>
>
>_______________________________________________
>netmod mailing list
>netmod@ietf.org
>https://www.ietf.org/mailman/listinfo/netmod