Re: [netmod] status-description (WAS Re: mbj review of draft-verdt-netmod-yang-module-versioning-01)
Hello,
While status-description is not a critical part of this work, it is still
useful, does not harm and is such a small addition, I do not understand why
Martin objects.
So why is status-description good:
Sometimes additional information is needed about deprecation, obsolescence:
- is the item still fully functional?
- when will its functionality be removed?
- when will the schema node itself be removed?
- is there a replacement or workaround that could/should be used instead of
deprecated/obsolete item?
The text can be used by tools. Using a separate statement to provide this
information is a method to separate the main description from this status
specific description.
In most cases both in the CLI and on NMS GUIs only the description is
displayed.
However there is a possibility to display the status information too.
In a way it is similar why we have separate description, contact, reference,
organization statements under module.
All these are just text, they could all be pushed under a single description
statement. Tools can't act on these automatically, still it is good to separate
them.
Regards Balazs
-Original Message-
From: netmod On Behalf Of Sterne, Jason (Nokia -
CA/Ottawa)
Sent: 2020. április 29., szerda 23:38
To: Reshad Rahman (rrahman) ; Martin
Björklund ; netmod@ietf.org
Subject: Re: [netmod] status-description (WAS Re: mbj review of
draft-verdt-netmod-yang-module-versioning-01)
I think we could wait until YANG 2.0 to add a description to the status.
Without a status description, an intelligent "YANG diff" of the models would
produce this:
a) new status deprecated statement
b) change to a description
With a status description we'd identify this:
a) new status deprecated statement
b) new status description
In both cases it is (a) that identifies the most clear information.
In both cases (b) provides no additional information that can be acted upon in
an automated fashion. The tool could only flag that (b) occurred in both cases
and a human would then have to go look at it.
If the only change between two versions of a module was a status description
change, then again a human would have to take a look. If we add some sort of
"nbc" tag to the leaf for tooling, then it also doesn't matter which
description changed.
Jason
> -Original Message-
> From: netmod On Behalf Of Reshad Rahman
> (rrahman)
> Sent: Friday, March 27, 2020 5:43 PM
> To: Martin Björklund ; netmod@ietf.org
> Subject: [netmod] rev:status-description (WAS Re: mbj review of
> draft-verdt-
> netmod-yang-module-versioning-01)
>
> Hi,
>
> https://github.com/netmod-wg/yang-ver-dt/issues/51
>
> o 3.4
>
> leaf imperial-temperature {
>type int64;
>units "degrees Fahrenheit";
>status deprecated {
> rev:status-description
>"Imperial measurements are being phased out in favor
> of their metric equivalents. Use metric-temperature
> instead.";
>}
>description
> "Temperature in degrees Fahrenheit.";
> }
>
> I don't think rev:status-description is necessary / worth it. This
> can easily be written with the normal description statement instead:
>
> leaf imperial-temperature {
>type int64;
>units "degrees Fahrenheit";
>status deprecated;
>description
>"Imperial measurements are being phased out in favor
> of their metric equivalents. Use metric-temperature
> instead.
>
> Temperature in degrees Fahrenheit.";
> }
>
> While rev:status-description isn't strictly necessary, without it we'd
> have to modify the node's description as you pointed out. That'd make
> tooling more
> difficult: is the description change BC or NBC? Also, a user looking
> at a diff would need to go through the description change. Use of
> rev:status- description makes this easier to handle.
>
> Regards,
> Reshad.
>
>
>
> On 2020-03-20, 5:08 PM, "netmod on behalf of Reshad Rahman (rrahman)"
> rrahman=40cisco@dmarc.ietf.org> wrote:
>
> Hi Martin,
>
> We've opened issues to track your review comments (see below).
> Will kick off separate therads for each issue.
>
> https://github.com/netmod-wg/yang-ver-
> dt/issues?q=is%3Aissue+is%3Aopen+label%3Aupdated-mod-rev-handling
>
> Regards,
> Reshad.
>
> On 2020-03-10, 3:31 PM, "netmod on behalf of Martin Björklund"
&
Re: [netmod] status-description (WAS Re: mbj review of draft-verdt-netmod-yang-module-versioning-01)
I think we could wait until YANG 2.0 to add a description to the status.
Without a status description, an intelligent "YANG diff" of the models would
produce this:
a) new status deprecated statement
b) change to a description
With a status description we'd identify this:
a) new status deprecated statement
b) new status description
In both cases it is (a) that identifies the most clear information.
In both cases (b) provides no additional information that can be acted upon in
an automated fashion. The tool could only flag that (b) occurred in both cases
and a human would then have to go look at it.
If the only change between two versions of a module was a status description
change, then again a human would have to take a look. If we add some sort of
"nbc" tag to the leaf for tooling, then it also doesn't matter which
description changed.
Jason
> -Original Message-
> From: netmod On Behalf Of Reshad Rahman
> (rrahman)
> Sent: Friday, March 27, 2020 5:43 PM
> To: Martin Björklund ; netmod@ietf.org
> Subject: [netmod] rev:status-description (WAS Re: mbj review of draft-verdt-
> netmod-yang-module-versioning-01)
>
> Hi,
>
> https://github.com/netmod-wg/yang-ver-dt/issues/51
>
> o 3.4
>
> leaf imperial-temperature {
>type int64;
>units "degrees Fahrenheit";
>status deprecated {
> rev:status-description
>"Imperial measurements are being phased out in favor
> of their metric equivalents. Use metric-temperature
> instead.";
>}
>description
> "Temperature in degrees Fahrenheit.";
> }
>
> I don't think rev:status-description is necessary / worth it. This
> can easily be written with the normal description statement instead:
>
> leaf imperial-temperature {
>type int64;
>units "degrees Fahrenheit";
>status deprecated;
>description
>"Imperial measurements are being phased out in favor
> of their metric equivalents. Use metric-temperature
> instead.
>
> Temperature in degrees Fahrenheit.";
> }
>
> While rev:status-description isn't strictly necessary, without it we'd have to
> modify the node's description as you pointed out. That'd make tooling more
> difficult: is the description change BC or NBC? Also, a user looking at a diff
> would need to go through the description change. Use of rev:status-
> description makes this easier to handle.
>
> Regards,
> Reshad.
>
>
>
> On 2020-03-20, 5:08 PM, "netmod on behalf of Reshad Rahman (rrahman)"
> rrahman=40cisco@dmarc.ietf.org> wrote:
>
> Hi Martin,
>
> We've opened issues to track your review comments (see below). Will kick
> off separate therads for each issue.
>
> https://github.com/netmod-wg/yang-ver-
> dt/issues?q=is%3Aissue+is%3Aopen+label%3Aupdated-mod-rev-handling
>
> Regards,
> Reshad.
>
> On 2020-03-10, 3:31 PM, "netmod on behalf of Martin Björklund" boun...@ietf.org on behalf of mbj+i...@4668.se> wrote:
>
> Hi,
>
> Here are my review comments of
> draft-verdt-netmod-yang-module-versioning-01.
>
>
>
> o 3.1.1
>
> o In statements that have any data definition statements as
>substatements, those data definition substatements MAY be
>reordered, as long as they do not change the ordering or any
> "rpc"
>"input" substatements.
>
> I think this needs to capture that no descendant statements to
> "input" can be reordered. Same for "output" (note, "input" and
> "output" in both "rpc" and "action").
>
>
> o 3.3
>
> All revision labels that match the pattern for the "version"
> typedef in the ietf-yang-semver YANG module MUST be interpreted as
> YANG semantic version numbers.
>
> I don't think this is a good idea. Seems like a layer violation.
> What if my project use another dialect of semver, that wouldn't be
> possible with this rule. I think this needs to be removed.
>
>
> o 3.3
>
> Submodules MUST NOT use revision label schemes that could be
> confused
> with the including module's revision label scheme.
>
> Hmm, how do I ensure that this MUST NOT is handled correctly? What
> exactly does "could be confused with" mean?
>
>
> o 3.3
>
> In the filename of a YANG module, where it takes the form:
> module-
> or-submodule-name ['@' revision-label] ( '.yang' / '.yin' )
>
> Should this section update 5.2 of RFC 7950? I know that 5.2 just
> says "SHOULD". But existing tools implement
