Subject: [Netmod-ver-dt] Problem statement about import by revision and early warning of removal

From: Balazs Lengyel <[email-masked]>
Date: Thu, 7 Jun 2018 15:41:30 +0200

Hello,
I wrote some text about the two topics.
regards Balazs

-------------------------------------------------------------------

Problems:

Early Warning about Removal
-----------------------------
If a schema part is considered old/bad we need to be able to give
advance warning that it will be removed.  As this is an advance
warning the part must still be present and usable in the current
revision; however, it will be removed in one of the next revisions.
The  deprecated statement cannot be reliably used for this purpose
both because deprecated nodes may not be implemented and also there
is no mandate that text be provided explaining the deprecation.

We need the advance warning to allow users of the module time
to plan/execute migration away from the deprecated functionality.
Often deprecation will be accompanied by information whether the
functionality will just disappear or that there is an alternative,
possibly more advanced solution that should be used.

Vendors use such warnings often, but the NMDA related redesign of
IETF modules is also an example where it would be useful for IETF. As
another example see the usage of deprecated in the Java programing
language.

No good way to specify which module revision to import
---------------------------------------------------------------------------
If a module (MOD-A) is imported by another one (MOD-B) the importer may 
specify
which revision must be imported. Even if MOD-A is developed in
backward-compatible steps not all revisions will be suitable,
e.g. a new MOD-B might need the newest MOD-A. However both specifying or
omitting the revision date for import leads to problems.

If the import by revision-date is specified
- If corrections are made to MOD-A these would not have any effect as the
import’s revision date would still point to the un-corrected earlier YAM 
revision.
- If MOD-A is developed in a backward-compatible way because another 
importer (MOD-C)
needs some functionality, the new MOD-A could be used by MOD-B, but 
specifying
the exact import revision-date prevents this. This will force the 
implementers to
import two different revisions of MOD-A, forcing them to maintain old MOD-A
revisions unnecessarily.
- If multiple modules import different revisions of MOD-A the human user 
will
need to understand the subtle differences between the different revisions.
Small differences would easily lead to operator mistakes as the operator 
will
rarely check the documentation.
- Tooling/SW is often not prepared to handle multiple revisions of the 
same YAM.

If the import revision-date is not specified
- any revision of MOD-A may be used including unsuitable ones. Older 
revisions
may be lacking functionality MOD-B needs. Newer MOD-A revisions may obsolete
definitions used by MOD-B in which case these must not be used by MOD-B 
anymore.
- As it is not specified which revisions of MOD-A
are suitable for MOD-B. The problem has to solved on a case by case basis
studying all the details of MOD-A and MOD-B which is a big work.

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909              email: [email-masked]

---

From: Benoit Claise <[email-masked]>
Date: Thu, 7 Jun 2018 16:24:55 +0200

Balazs,

Please provide a PR, as I was not sure how to apply it since your text 
below "Early Warning about Removal" is already part of the "2.6. Clear 
Indication of Node Support" in the current draft.

Regards, Benoit
> If a module (MOD-A) is imported by another one (MOD-B) the importer 
> may specify
> import’s revision date would still point to the un-corrected earlier 
> YAM revision.
> - If multiple modules import different revisions of MOD-A the human 
> user will
> Small differences would easily lead to operator mistakes as the 
> operator will
> definitions used by MOD-B in which case these must not be used by 
> MOD-B anymore.
b

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 7 Jun 2018 10:23:01 -0700

Also, it is not clear what the client is supposed to do with this “early warning” system that is different from a deprecated statement.

> On Jun 7, 2018, at 7:24 AM, Benoit Claise <bclaise=[email-masked]> wrote:
> 
> Balazs,
> 
> Please provide a PR, as I was not sure how to apply it since your text below "Early Warning about Removal" is already part of the "2.6. Clear Indication of Node Support" in the current draft.
> 
> Regards, Benoit
>> Hello, 
>> If a module (MOD-A) is imported by another one (MOD-B) the importer may specify 
>> import’s revision date would still point to the un-corrected earlier YAM revision. 
>> - If MOD-A is developed in a backward-compatible way because another importer (MOD-C) 
>> needs some functionality, the new MOD-A could be used by MOD-B, but specifying 
>> the exact import revision-date prevents this. This will force the implementers to 
>> - If multiple modules import different revisions of MOD-A the human user will 
>> Small differences would easily lead to operator mistakes as the operator will 
>> - Tooling/SW is often not prepared to handle multiple revisions of the same YAM. 
>> 
>> - any revision of MOD-A may be used including unsuitable ones. Older revisions 
>> definitions used by MOD-B in which case these must not be used by MOD-B anymore. 
> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

Mahesh Jethanandani
[email-masked]

---

From: Robert Wilton <[email-masked]>
Date: Fri, 8 Jun 2018 12:19:24 +0100

Hi Mahesh,

I think that Balazs is really trying to find an acceptable way to change 
the definition of YANG status: deprecated from "may or may not be 
supported" to "is still supported now, but it likely to be removed in a 
future revision".

If something is deprecated then there are two useful additional pieces 
of information that could potentially be to provided to a client (if known):

(i) When will the node likely be removed.
(ii) What is the alternative node(s) (if any).

I guess that I see that this could be a "status" specific description 
statement that it meant to help provide lifecycle information to 
clients.  An alternative would be just to embed that information in the 
modules top level revision statement, but that may not work so well with 
tools like YANG catalog that are presenting information on a per schema 
node basis.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 8 Jun 2018 13:39:02 +0200

On Fri, Jun 08, 2018 at 12:19:24PM +0100, Robert Wilton wrote:
> Hi Mahesh,
> 
> I think that Balazs is really trying to find an acceptable way to change the
> definition of YANG status: deprecated from "may or may not be supported" to
> "is still supported now, but it likely to be removed in a future revision".
> 
> If something is deprecated then there are two useful additional pieces of
> information that could potentially be to provided to a client (if known):
> 
> statement that it meant to help provide lifecycle information to clients. 
> An alternative would be just to embed that information in the modules top
> level revision statement, but that may not work so well with tools like YANG
> catalog that are presenting information on a per schema node basis.
>

What speaks against simply adding a sentence to the regular
description statement? See RFC 8096 for an example how this was done
for obsolete MIB object definitions.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 8 Jun 2018 13:47:00 +0200

Hello,

I want to provide the info as Rob stated. I also MUST have a
guarantee that:

While the schema node will be removed in the future it is still
fully functional in the revision that carries the
balazs-deprecated statement.

If the schema node may or may not be present I can not depend on
it anymore.

The ideal solution would be:

balazs-deprecated means still present and fully functional

a status-info substatement (to status) that allows me to
specify whether the schema node is just removed or replaced by
something.

IMHO the status-info relay belongs to the schema node and should
not be put into the module's top level revision statement

status information maybe very different for different
balazs-deprecated nodes

Might make the top-revision long

status info might be valid for more then one revision, so
selectively copying it over to the next revision statement would
be a hassle

reader would need to page up and down to find the info using
line numbers or XPath schema node identifiers

status info is really connected to the schema node, so it
should be documented there.

regards Balazs

P.S. IMHO it is a bug in yang 1.1 that deprecated items may or
may not be there.

On 6/8/2018 1:19 PM, Robert Wilton
wrote:

Hi
Mahesh,

I think that Balazs is really trying to find an acceptable way to
change the definition of YANG status: deprecated from "may or may
not be supported" to "is still supported now, but it likely to be
removed in a future revision".

If something is deprecated then there are two useful additional
pieces of information that could potentially be to provided to a
client (if known):

I guess that I see that this could be a "status" specific
description statement that it meant to help provide lifecycle
information to clients.  An alternative would be just to embed
that information in the modules top level revision statement, but
that may not work so well with tools like YANG catalog that are
presenting information on a per schema node basis.

Thanks,

Rob

Also, it is not clear what the client is
supposed to do with this “early warning” system that is
different from a deprecated statement.

On Jun 7, 2018, at 7:24 AM, Benoit
Claise <bclaise=[email-masked]> wrote:

Balazs,

Please provide a PR, as I was not sure how to apply it since
your text below "Early Warning about Removal" is already part
of the "2.6. Clear Indication of Node Support" in the current
draft.

Regards, Benoit

Hello,

regards Balazs

Problems:

If a schema part is considered old/bad we need to be able to
give

advance warning that it will be removed.  As this is an
advance

warning the part must still be present and usable in the
current

revision; however, it will be removed in one of the next
revisions.

The  deprecated statement cannot be reliably used for this
purpose

both because deprecated nodes may not be implemented and
also there

is no mandate that text be provided explaining the
deprecation.

We need the advance warning to allow users of the module
time

to plan/execute migration away from the deprecated
functionality.

Often deprecation will be accompanied by information whether
the

functionality will just disappear or that there is an
alternative,

Vendors use such warnings often, but the NMDA related
redesign of

IETF modules is also an example where it would be useful for
IETF. As

another example see the usage of deprecated in the Java
programing

language.

If a module (MOD-A) is imported by another one (MOD-B) the
importer may specify

which revision must be imported. Even if MOD-A is developed
in

backward-compatible steps not all revisions will be
suitable,

e.g. a new MOD-B might need the newest MOD-A. However both
specifying or

- If corrections are made to MOD-A these would not have any
effect as the

import’s revision date would still point to the un-corrected
earlier YAM revision.

- If MOD-A is developed in a backward-compatible way because
another importer (MOD-C)

needs some functionality, the new MOD-A could be used by
MOD-B, but specifying

the exact import revision-date prevents this. This will
force the implementers to

import two different revisions of MOD-A, forcing them to
maintain old MOD-A

revisions unnecessarily.

- If multiple modules import different revisions of MOD-A
the human user will

need to understand the subtle differences between the
different revisions.

Small differences would easily lead to operator mistakes as
the operator will

- Tooling/SW is often not prepared to handle multiple
revisions of the same YAM.

- any revision of MOD-A may be used including unsuitable
ones. Older revisions

may be lacking functionality MOD-B needs. Newer MOD-A
revisions may obsolete

definitions used by MOD-B in which case these must not be
used by MOD-B anymore.

are suitable for MOD-B. The problem has to solved on a case
by case basis

studying all the details of MOD-A and MOD-B which is a big
work.

b

[email-masked]

Mahesh Jethanandani

[email-masked]

[email-masked]

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 8 Jun 2018 13:58:25 +0200

Hello,
I want to provide the info as Rob stated. I also MUST have a guarantee that:
While the schema node will be removed in the future it is still fully 
functional in the revision that carries the balazs-deprecated statement.

Solving this second part with a description statement is not OK.

IMHO having a status-info substatement / extension statement for the 
status statement is a cleaner solution. It puts the information where it 
belongs. It is really information about why and how the item was 
deprecated. It does not change the general behavior/properties of the 
schema node. Still if there is significant opposition to status-info, we 
could put that into the description of the schema node.

This is how we do it in Ericsson

     extension status-information {
         description "Information related to the value of
             status, SHOULD describe if the schema node was removed
             or replaced by an alternative solution.

             The statement MUST only be a substatement to the YANG
             status statement.
             Zero or one status-information statement per status is allowed.
             MUST NOT be present if the status is current.
             NO substatements are allowed.

             The argument value can be any text.";

         argument "text";

     }

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 8 Jun 2018 14:16:26 +0200

On Fri, Jun 08, 2018 at 01:58:25PM +0200, Balazs Lengyel wrote:
> IMHO having a status-info substatement / extension statement for the status
> statement is a cleaner solution. It puts the information where it belongs.
> It is really information about why and how the item was deprecated. It does
> not change the general behavior/properties of the schema node. Still if
> there is significant opposition to status-info, we could put that into the
> description of the schema node.
>

I have no strong opinion about this. If people want to have a
description statement as a substatement of the status statement,
so be it. I was just pointing out that even today there are ways
to document why something got deprecated or obsoleted.

/js

---

From: Robert Wilton <[email-masked]>
Date: Fri, 8 Jun 2018 14:44:05 +0100

> for obsolete MIB object definitions.
I would say that adding additional information to the data node 
description is a convention based approach that works now, but would 
rely on folks being aware of the convention.  However, I don't think 
that it is quite so friendly for tooling.  E.g. if diffing between two 
YANG modules, ideally want to report that the lifecycle has changed 
rather than the description of the data node.  If the YANG hood is up 
for other reasons then allowing a description statement under status 
seems like a small but potentially useful addition.

Thanks,
Rob

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Fri, 8 Jun 2018 13:46:00 +0000

I agree with Rob's statement below.

On 2018-06-08, 9:44 AM, "Netmod-ver-dt on behalf of Robert Wilton" <[email-masked] on behalf of rwilton=[email-masked]> wrote:

    
    Thanks,
    Rob

---

From: Kent Watsen <[email-masked]>
Date: Mon, 18 Jun 2018 16:55:53 +0000

[just peeking, but couldn't resist]

When I did this in a past life, we had two nodes:

 - a "supported-until" node that specified a date in the future (typically 
   one year after public release), after which the node MAY disappear 
   without notice.  This was of type date-and-time for programmatic 
   consumption.

 - a "remediation" node (type: string) that provided human text for how 
   the clients should be adjusted.

/kw

    
    
    Thanks,
    Rob
    
    _______________________________________________
    Netmod-ver-dt mailing list
    [email-masked]
    https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod-2Dver-2Ddt&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=neyqtZVBrSTs6O7OON349Jl1VemCi4YuI9GTerVaUOE&s=I_Y3YbOK5T-qqW9MkGekkayAW_MgXxSs1fzq7QcaJJ4&e=

_______________________________________________
Netmod-ver-dt mailing list
[email-masked]
https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod-2Dver-2Ddt&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=neyqtZVBrSTs6O7OON349Jl1VemCi4YuI9GTerVaUOE&s=I_Y3YbOK5T-qqW9MkGekkayAW_MgXxSs1fzq7QcaJJ4&e=