Re: [yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules
Mahesh Jethanandani <mjethanandani@gmail.com> Wed, 06 December 2023 15:40 UTC
Return-Path: <mjethanandani@gmail.com>
X-Original-To: yang-doctors@ietfa.amsl.com
Delivered-To: yang-doctors@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id D9F10C14F5E7 for <yang-doctors@ietfa.amsl.com>; Wed, 6 Dec 2023 07:40:26 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -7.106
X-Spam-Level:
X-Spam-Status: No, score=-7.106 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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_HI=-5, RCVD_IN_ZEN_BLOCKED_OPENDNS=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01, URIBL_DBL_BLOCKED_OPENDNS=0.001, URIBL_ZEN_BLOCKED_OPENDNS=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com
Received: from mail.ietf.org ([50.223.129.194]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id uy9rSELFM8Hh for <yang-doctors@ietfa.amsl.com>; Wed, 6 Dec 2023 07:40:22 -0800 (PST)
Received: from mail-pf1-x42e.google.com (mail-pf1-x42e.google.com [IPv6:2607:f8b0:4864:20::42e]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 90E85C14F5E0 for <yang-doctors@ietf.org>; Wed, 6 Dec 2023 07:40:22 -0800 (PST)
Received: by mail-pf1-x42e.google.com with SMTP id d2e1a72fcca58-6ce76f0748fso1404121b3a.2 for <yang-doctors@ietf.org>; Wed, 06 Dec 2023 07:40:22 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1701877221; x=1702482021; darn=ietf.org; h=to:references:message-id:date:cc:in-reply-to:from:mime-version :subject:content-transfer-encoding:from:to:cc:subject:date :message-id:reply-to; bh=zssBTO+0r0froQYN3jjpO/Txw7GoXBTA/CxfC7EQkyQ=; b=Ve6J3ZTYUYGcOSW9vbSqBW6QSN4Ikuu87+ejNsPSI+6SVul9r0InYJIleWqxcAvI8s jbI69zqKVZ2fLwIA4IL3lfxWZ3WbXYZ0EAofm4T/tqHXAzTjiplqPXp9/j0LtS4sHMER UF1UpB7zctp/yx4d7Y8oYAatVQxwm8LVKxnITc0al8xdsogFmhIjR3J++TBR529hs5tf fMapKY1osAOlQDw6OG4tFjacvPmmI8hV6XexK+XcQIzEkhOk2C9hQiZQKx3zPX9/3Z1Z ycMkbQuN+DxRoYZRuwV/KNse4TKFy+f8y0O0ANhQet2A7LiOW+HXKvhncwuJgC7DTnKz penA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1701877221; x=1702482021; h=to:references:message-id:date:cc:in-reply-to:from:mime-version :subject:content-transfer-encoding:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=zssBTO+0r0froQYN3jjpO/Txw7GoXBTA/CxfC7EQkyQ=; b=ZxVCRbipGlgBYzjxpZMk/QYEY4u3Zqu9iAbG5jPAF1EZzsKV880v807rCc9+f68FJ3 MdR6Nn3S4jqdg9oA6yjGLgPYyEYyOGlhVUsVHLyZUX1clTczUxrrRqsY+nT7Ex3jx0Um lpgRBbSMnG/+kNDZtSaXkZISkDuB/US0ZSDclMR3/gkVwYrtuM/FVzh5KE5eT42BxEwz g+gyeUHKfwQJyrlyCfFOj4GkGmUE4X5kboU/X0AV2BBAxPnjPET2ZY0HFKCQYvCEPKVP LHeg1e8zBb9XqJAK7MlqKpZC8bzcGlVAEHw5noACVj8HLB5mjaPcjLdrLSORkRAOUusm XWmQ==
X-Gm-Message-State: AOJu0YzYvd25EDOqEJ73pwBiFOBNLNlyNQSxla9nmKlb6veO8TQAh6tF Np0aMG5UDdcQayQtipZzpnr7SC+dwII=
X-Google-Smtp-Source: AGHT+IFrHcuGBmmKXlXU4XNpAZvaNhU42wZfdJs5cBCbbIYaKKmFT30MZuui0d8vtYnIN9NiHaT75A==
X-Received: by 2002:a05:6a20:a426:b0:15b:c800:48af with SMTP id z38-20020a056a20a42600b0015bc80048afmr748524pzk.23.1701877220813; Wed, 06 Dec 2023 07:40:20 -0800 (PST)
Received: from smtpclient.apple (c-69-181-169-15.hsd1.ca.comcast.net. [69.181.169.15]) by smtp.gmail.com with ESMTPSA id p1-20020a63b801000000b005c19c586cb7sm65816pge.33.2023.12.06.07.40.20 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 06 Dec 2023 07:40:20 -0800 (PST)
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (1.0)
X-Apple-Notify-Thread: NO
X-Universally-Unique-Identifier: 7AE0A4B8-6CAB-4162-883C-F5E9967ABB15
From: Mahesh Jethanandani <mjethanandani@gmail.com>
In-Reply-To: <rt-5.0.3-1585205-1701829314-1497.1289473-37-0@icann.org>
Cc: yang-doctors@ietf.org
Date: Wed, 06 Dec 2023 07:40:09 -0800
X-Apple-Message-Smime-Encrypt: NO
Message-Id: <2279F086-FC49-414F-A36A-007567BC9D93@gmail.com>
References: <rt-5.0.3-1585205-1701829314-1497.1289473-37-0@icann.org>
To: iana-issues@iana.org
X-Mailer: iPhone Mail (20D67)
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/ofSnZ2lV0Zx0cA4OPJh3mv-EGbE>
Subject: Re: [yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules
X-BeenThere: yang-doctors@ietf.org
X-Mailman-Version: 2.1.39
Precedence: list
List-Id: Email list of the yang-doctors directorate <yang-doctors.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/yang-doctors/>
List-Post: <mailto:yang-doctors@ietf.org>
List-Help: <mailto:yang-doctors-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 06 Dec 2023 15:40:26 -0000
Not from my side. Thanks Mahesh Jethanandani mjethanandani@gmail.com > On Dec 5, 2023, at 6:22 PM, Amanda Baber via RT <iana-issues@iana.org> wrote: > > Hi all, > > Sending a reminder for this one. Are there any objections to these processing instructions for IANA-maintained modules? > >> 1. Publish the initial version of the module as-is from the RFC. >> >> 2. When the module is updated the first time, change the "This >> version of >> this YANG module..." as discussed [below]. >> >> 3. For every module update, add a "revision" statement with a >> "reference" statement that refers to the published module (e.g., >> https://www.iana.org/assignments/yang-parameters/iana-dns-class- >> rr-type@2023-11-08.yang) > > Please see below. > > thanks, > Amanda > >> On Wed Nov 29 12:07:59 2023, mbj+ietf@4668.se wrote: >> Hi, >> >> "Amanda Baber via RT" <iana-issues@iana.org> wrote: >>> Hi all, >>> >>> First, we understand that existing revision statements in >>> IANA-maintained modules should be left alone. >>> >>> A few questions: >>> >>> 1) When we first add an entry to an IANA-maintained module, should >>> we, >>> as Martin suggested, change, e.g. "This version of this YANG module >>> is >>> part of RFC 8294; see the RFC itself for full legal notices." to >>> "This >>> original version of this YANG module is part of RFC 8294; see the RFC >>> itself for full legal notices."? >> >> I think so, but I would like to hear what others have to say. >> >> >>> >>> 2a) Is it agreed that if IANA registers a codepoint in a First Come >>> First Served or Expert Review range, and there is no associated >>> specification, IANA will list a URL? >>> >>> 2b) If the registration is in the RRTYPE registry in >>> https://www.iana.org/assignments/dns-parameters, would that reference >>> be to https://www.iana.org/assignments/dns-parameters, >>> https://www.iana.org/assignments/iana-dns-class-rr-type [1], or for >>> example, >>> https://www.iana.org/assignments/yang-parameters/iana-dns-class-rr- >>> type@2023-11-08.yang? >>> >>> [1] We prefer to leave out the trailing >>> "/iana-dns-class-rr-type.xhtml" in case other extensions are >>> preferred >>> in the future, although the .xhtml version will continue to work. >> >> The motivation behind the rule is to make it easy for readers of a >> module to find the original source of the module. In the example >> above, I think that the reference to >> https://www.iana.org/assignments/dns-parameters should be in the >> module's reference statement, which it is. >> >> So I'd say either one of >> https://www.iana.org/assignments/iana-dns-class-rr-type or >> https://www.iana.org/assignments/yang-parameters/iana-dns-class-rr- >> type@2023-11-08.yang >> (see more below). >> >> >>> >>> 2c) About this: >>> >>>> When I validate this module directly with pyang, I get the errors: >>>> >>>> $ pyang --ietf iana-routing-types@2022-08-19.yang >>>> iana-routing-types@2022-08-19.yang:35: error: RFC 8407: 4.8: >>>> statement >>>> "revision" must have a "reference" substatement >>> >>> We were using https://yangcatalog.org/yangvalidator, which is where >>> we >>> came across the ietf-* vs. iana-* reference discrepancy. We've since >>> started using pyang. >>> >>> Something I should note here is that IANA operations staff (as >>> opposed >>> to its technical staff, which includes regular and irregular IETF >>> participants) are not only not expert in YANG but are also, >>> essentially, liberal arts majors who have learned to use command line >>> tools and markup languages as needed. (I also have a two-year >>> programming degree that involved about half an hour of JSON, which is >>> why I get to be the delegate here.) >> >> Ok. So perhaps the simplest solution would be: >> >> 1. Publish the initial version of the module as-is from the RFC. >> >> 2. When the module is updated the first time, change the "This >> version of >> this YANG module..." as discussed above. >> >> 3. For every module update, add a "revision" statement with a >> "reference" statement that refers to the published module (e.g., >> https://www.iana.org/assignments/yang-parameters/iana-dns-class- >> rr-type@2023-11-08.yang) >> >> >> >> As an alternative, if we decide that IANA-maintained modules don't >> need "reference" in "revision", I can add a flag "--iana" to pyang >> that would implement this. But in this case, we should probably add >> the URL to the IANA registry (e.g., >> https://www.iana.org/assignments/iana-dns-class-rr-type) somewhere, >> probably in the module's "description". >> >> >> /martin >> >> >> >>> >>> Where RFC 8407 is concerned, we acted on the IANA Considerations >>> section only, and didn't recognize that (as actors on modules) we >>> need >>> to implement certain other sections of that document. We've relied on >>> online validation tools, as we had/have with MIB modules. >>> >>> I think we need a tutorial before we re-approach RFC 8407 and turn >>> our >>> internal module maintenance notes into an internal manual (which if >>> not already necessary will certainly be so when >>> draft-ietf-netmod-yang-module-versioning and >>> draft-ietf-netmod-yang-semver arrive). Are there resources you can >>> recommend? >>> >>> thanks, >>> Amanda >>> >>> On Thu Nov 23 07:39:39 2023, mbj+ietf@4668.se wrote: >>>> Ladislav Lhotka <ladislav.lhotka@nic.cz> wrote: >>>>> Dne 22. 11. 23 v 11:24 Martin Björklund napsal(a): >>>>>> Hi, >>>>>> Ladislav Lhotka <ladislav.lhotka=40nic.cz@dmarc.ietf.org> >>>>>> wrote: >>>>>>> Hi Amanda, >>>>>>> >>>>>>> "Amanda Baber via RT" <iana-issues@iana.org> writes: >>>>>>> >>>>>>>> Hi, >>>>>>>> >>>>>>>> We came across an issue when attempting to validate RFC >>>>>>>> 9403's >>>>>>>> ietf-rib-extension@2023-11-20.yang module before posting. >>>>>>>> >>>>>>>> That module refers to iana-routing-types@2022-08-19.yang, and >>>>>>>> pyang is >>>>>>>> refusing to validate it on the grounds that >>>>>>>> iana-routing-types@2022-08-19.yang doesn't have references >>>>>>>> for >>>>>>>> its >>>>>>>> revision statements. (Which it indeed does not.) >>>>>>>> >>>>>>>> However, if we try to validate iana-routing-types@2022-08- >>>>>>>> 19.yang >>>>>>>> directly, we don't get any errors. >>>>>>>> >>>>>>>> Which pyang reaction is correct? >>>>>> When I validate this module directly with pyang, I get the >>>>>> errors: >>>>>> $ pyang --ietf iana-routing-types@2022-08-19.yang >>>>>> iana-routing-types@2022-08-19.yang:35: error: RFC 8407: 4.8: >>>>>> statement >>>>>> "revision" must have a "reference" substatement >>>>>> ... >>>>>> >>>>>>> >>>>>>> RFC 8407 states in sec. 4.8: >>>>>>> >>>>>>> The "revision" statement MUST have a "reference" substatement. >>>>>>> >>>>>>> The module description refers to RFC 8294 though, and I am not >>>>>>> sure >>>>>>> how this particular module is updated and whether there is >>>>>>> always >>>>>>> a >>>>>>> relevant reference available for a given revision. >>>>>>> >>>>>>>> >>>>>>>> One larger issue is that we weren't aware that we needed to >>>>>>>> add >>>>>>>> references for revision statements in the IANA-maintained >>>>>>>> modules. We >>>>>>>> have no expertise in YANG and have been relying entirely on >>>>>>>> validation >>>>>>>> tools (and on IANA Considerations sections for registry >>>>>>>> maintenance >>>>>>>> instructions in general). >>>>>>>> >>>>>>>> Should we go back and add references to revision statements >>>>>>>> for >>>>>>>> all >>>>>>>> the IANA-maintained modules? >>>>>>> >>>>>>> This could lead to problems with versioning of modules. >>>>>>> >>>>>>>> >>>>>>>> Do we need to do so only going forward? >>>>>>> >>>>>>> I'd suggest to add reference statements to future >>>>>>> (substantial) >>>>>>> revisions of modules, perhaps even retroactively, but only >>>>>>> where >>>>>>> it >>>>>>> makes sense. >>>>>>> >>>>>>>> >>>>>>>> Either way, we have two questions: >>>>>>>> >>>>>>>> 1) Many of the registries mirrored by the IANA-maintained >>>>>>>> modules >>>>>>>> have >>>>>>>> First Come First Served or Expert Review ranges that don't >>>>>>>> require >>>>>>>> that the applicant provide a specification. For those >>>>>>>> registrations, >>>>>>>> we list the name of a contact person in the registry's >>>>>>>> "Reference" >>>>>>>> field. In the module, would we continue to omit the reference >>>>>>>> field? >>>>>>> >>>>>>> If there is no suitable document to refer to, it makes no >>>>>>> sense to >>>>>>> me >>>>>>> to add any stub references. RFC 8407 is IMO unnecesarily >>>>>>> strict >>>>>>> here, >>>>>>> and a SHOULD might suffice. >>>>>> The full text in RFC 8407 is: >>>>>> A "revision" statement MUST be present for each published >>>>>> version of >>>>>> the module. The "revision" statement MUST have a >>>>>> "reference" >>>>>> substatement. It MUST identify the published document that >>>>>> contains >>>>>> the module. >>>>>> In this case, there really isn't any "published document" - the >>>>>> module >>>>>> is published directly on the web. One option could be to add >>>>>> the >>>>>> URL >>>>>> to the module in "reference". The motivation for the rule is: >>>>> >>>>> Right, but this link to the authoritative registry page belongs >>>>> to >>>>> the >>>>> "reference" statement that is a direct substatement of "module" >>>>> (see >>>>> e.g. [1]). The problem here is that RFC 8407 requires *every* >>>>> "revision" statement to contain "reference". >>>>> >>>>> Lada >>>>> >>>>> [1] >>>>> https://www.iana.org/assignments/iana-dns-class-rr-type/iana-dns- >>>>> class-rr-type.xhtml >>>> >>>> In this example, the module's "reference" is >>>> >>>> https://www.iana.org/assignments/dns-parameters >>>> >>>> >>>> >>>> I was thinking the revision's "reference" could be >>>> >>>> https://www.iana.org/assignments/iana-dns-class-rr-type/iana-dns- >>>> class-rr-type.xhtml >>>> >>>> or even >>>> >>>> https://www.iana.org/assignments/yang-parameters/iana-dns-class-rr- >>>> type@2023-11-08.yang >>>> >>>> >>>> >>>> /martin >>>> >>>> >>>> >>>>> >>>>>> Modules are often extracted from their original >>>>>> documents, and it is useful for developers and operators to >>>>>> know >>>>>> how >>>>>> to find the original source document in a consistent manner. >>>>>> So the URL would help for this. >>>>>> Side note. In the description of the module it says: >>>>>> This version of this YANG module is part of RFC 8294; see >>>>>> the RFC itself for full legal notices."; >>>>>> This isn't true... Should IANA change the description of the >>>>>> module >>>>>> when it updates the module? Perhaps to: >>>>>> This original version of this YANG module is part of RFC >>>>>> 8294; >>>>>> see >>>>>> the RFC itself for full legal notices."; >>>>>> /martin >>>>>> >>>>>>> >>>>>>>> >>>>>>>> 2) When we need to correct an IANA-maintained module, in the >>>>>>>> absence >>>>>>>> of a document to refer to, what can we do to make the >>>>>>>> revision >>>>>>>> statement valid? >>>>>>> >>>>>>> I'd say yes. >>>>>>> >>>>>>> Best regards, Lada >>>>>>> >>>>>>>> >>>>>>>> Best regards, >>>>>>>> >>>>>>>> Amanda Baber >>>>>>>> IANA Operations Manager >>>>>>>> >>>>>>>> _______________________________________________ >>>>>>>> yang-doctors mailing list >>>>>>>> yang-doctors@ietf.org >>>>>>>> https://www.ietf.org/mailman/listinfo/yang-doctors >>>>>>> >>>>>>> -- >>>>>>> Ladislav Lhotka, CZ.NIC >>>>>>> PGP Key ID: 0xB8F92B08A9F76C67 >>>>>>> >>>>>>> _______________________________________________ >>>>>>> yang-doctors mailing list >>>>>>> yang-doctors@ietf.org >>>>>>> https://www.ietf.org/mailman/listinfo/yang-doctors >>>>> >>>>> -- >>>>> Ladislav Lhotka, CZ.NIC >>>>> PGP Key ID: 0xB8F92B08A9F76C67 >>> >>> _______________________________________________ >>> yang-doctors mailing list >>> yang-doctors@ietf.org >>> https://www.ietf.org/mailman/listinfo/yang-doctors > > _______________________________________________ > yang-doctors mailing list > yang-doctors@ietf.org > https://www.ietf.org/mailman/listinfo/yang-doctors
- [yang-doctors] [IANA #1289473] Revision statement… Amanda Baber via RT
- Re: [yang-doctors] [IANA #1289473] Revision state… Ladislav Lhotka
- Re: [yang-doctors] [IANA #1289473] Revision state… Martin Björklund
- Re: [yang-doctors] [IANA #1289473] Revision state… Ladislav Lhotka
- Re: [yang-doctors] [IANA #1289473] Revision state… Martin Björklund
- [yang-doctors] [IANA #1289473] Revision statement… Amanda Baber via RT
- Re: [yang-doctors] [IANA #1289473] Revision state… Martin Björklund
- [yang-doctors] [IANA #1289473] Revision statement… Amanda Baber via RT
- Re: [yang-doctors] [IANA #1289473] Revision state… Ladislav Lhotka
- Re: [yang-doctors] [IANA #1289473] Revision state… Acee Lindem
- Re: [yang-doctors] [IANA #1289473] Revision state… Mahesh Jethanandani
- [yang-doctors] [IANA #1289473] Revision statement… Amanda Baber via RT