Subject: [Netconf] Review notes on YANG Patch

From: Mahesh Jethanandani <[email-masked]>
Date: Sun, 25 Sep 2016 23:25:43 -0700

[Resending with NETCONF mailing list added]

Authors,

I have reread the latest version of YANG Patch draft (-11) and also went back to the beginning of this year to track the reviews done on the document and to see if the comments from the review have been addressed.

Existence of two delete operations(“delete” and “remove”) is confusing (at least to me). We say that these operations are aligned with the NETCONF edit operations, but we do not reference them. “delete” is defined as “delete a data resource if it already exists or error”, while “remove” is defined as “remove a data resource if it already exists”. Andy clarified this on github, saying one was “picky” and the other “not so picky”. If the definition is the same as NETCONF, can we reference it, or better still state it the same way here, leaving no ambiguity on how 'remove' is different from ‘delete’?
Does yang-patch allow a whole list to be deleted? This was raised by Lada, and was subsequently discussed on the mailing list, but the draft is silent on it. Again, Andy clarifies in github, but the draft is not clear. Can we clarify it in the draft?
Why is patch-id optional? This was raised by Lada. Would it make sense to make this field mandatory so there is a way to track which patch operations failed, for example. But this somehow got dropped in github. Can we address it?
How does one patch multiple datastores? This was raised by Juergen. The introduction says it is outside the scope. Even if I accept it, we need to leave room for supporting other datastore, e.g. ephemeral. Would it be possible to reference another datastore? If so, how? If not, is this not a limitation?
Benoit noticed that Section 1.1.7 says “Tree Diagrams” instead of “Tree Diagram Notations”. Can we change it?
Benoit made a point that “yang-patch Input” and “yang-patch Output” is not congruent with request and response in the HTTP world. Can we call it “yang-patch Request” and “yang-patch Response”?
My earlier read of the draft was that a complete replace of the datastore was possible with RESTCONF. But I see I have been corrected by Andy. Benoit also asked it to be made clear. But then in an exchange with Steve Troung, there was some talk about using  PUT on a datastore resource. I am confused. Can the entire datastore be replaced? if not, can this be clarified?
Benoit had a comment on appendix example D.1.4, where he was not clear on the atomicity rules. Specifically, the question of what happens if there are three edit operations and edit2 fails. Does edit1 rollback? If so, how? He made two conclusions on the example, which I agree with him on. That the router has to have either only one edit per request or it support candidate configuration for it to be able to rollback. If we feel the example is important, we will have to provide the full context of what we describe as “conceptual datastore” by describing the assumptions we are making, i.e. the two conclusions Beniot came to, to make sense of the example. Do others disagree?

I would ideally like to close on these comments latest by Oct 10.

Thanks.

Mahesh Jethanandani
[As document shepherd]

---

From: Andy Bierman <[email-masked]>
Date: Mon, 26 Sep 2016 09:42:44 -0700

On Sun, Sep 25, 2016 at 11:25 PM, Mahesh Jethanandani <
[email-masked]> wrote:

> I have reread the latest version of YANG Patch draft (-11) and also went
> back to the beginning of this year to track the reviews done on the
> document and to see if the comments from the review have been addressed.
>
>
>    - Existence of two delete operations(“delete” and “remove”) is
>    confusing (at least to me). We say that these operations are aligned with
>    the NETCONF edit operations, but we do not reference them. “delete” is
>    defined as “delete a data resource if it already exists or error”, while
>    “remove” is defined as “remove a data resource if it already exists”. Andy
>    clarified this on github, saying one was “picky” and the other “not so
>    picky”. If the definition is the same as NETCONF, can we reference it, or
>    better still state it the same way here, leaving no ambiguity on how
>    'remove' is different from ‘delete’?
>
>

added text  referencing NETCONF

>    - Does yang-patch allow a whole list to be deleted? This was raised by
>    Lada, and was subsequently discussed on the mailing list, but the draft is
>    silent on it. Again, Andy clarifies in github, but the draft is not clear.
>    Can we clarify it in the draft?
>
>

added text that each edit MUST represent a single data resource instance

>
>    - Why is patch-id optional? This was raised by Lada. Would it make
>    sense to make this field mandatory so there is a way to track which patch
>    operations failed, for example. But this somehow got dropped in github. Can
>    we address it?
>
>
made patch-id mandatory (can be the empty string)

>
>    - How does one patch multiple datastores? This was raised by Juergen.
>    The introduction says it is outside the scope. Even if I accept it, we need
>    to leave room for supporting other datastore, e.g. ephemeral. Would it be
>    possible to reference another datastore? If so, how? If not, is this not a
>    limitation?
>
>
multiple datastores are not supported at and will not be supported
at all by the document. There is no mechanism to reference any datastore.
The target resource URI is referenced from RESTCONF.
[no edits]

>    - Benoit noticed that Section 1.1.7 says “Tree Diagrams” instead of
>    “Tree Diagram Notations”. Can we change it?
>
>
changed section title

>
>    - Benoit made a point that “yang-patch Input” and “yang-patch Output”
>    is not congruent with request and response in the HTTP world. Can we call
>    it “yang-patch Request” and “yang-patch Response”?
>
>
changed section titles

>
>    - My earlier read of the draft was that a complete replace of the
>    datastore was possible with RESTCONF. But I see I have been corrected by
>    Andy. Benoit also asked it to be made clear. But then in an exchange with
>    Steve Troung, there was some talk about using  PUT on a datastore resource.
>    I am confused. Can the entire datastore be replaced? if not, can this be
>    clarified?
>
>
clarified that YANG Patch provides no direct access to datastores and a
datastore cannot be replaced like with PUT

>
>    - Benoit had a comment on appendix example D.1.4, where he was not
>    clear on the atomicity rules. Specifically, the question of what happens if
>    there are three edit operations and edit2 fails. Does edit1 rollback? If
>    so, how? He made two conclusions on the example, which I agree with him on.
>    That the router has to have either only one edit per request or it support
>    candidate configuration for it to be able to rollback. If we feel the
>    example is important, we will have to provide the full context of what we
>    describe as “conceptual datastore” by describing the assumptions we are
>    making, i.e. the two conclusions Beniot came to, to make sense of the
>    example. Do others disagree?
>
>
>

text already has:

A PATCH request MUST be applied atomically, as specified
in section 2 of ^RFC5789^.

[no edits]

> I would ideally like to close on these comments latest by Oct 10.
github is ready with draft-12