[yang-doctors] Re: Examples for groupings (was RE: Yangdoctors early review of draft-ietf-netmod-schedule-yang-02)

[Reshad Rahman <[e-mail]>]

 Hi Med, all,
> Do we need to be consistent in how various I-Ds proceed here? Should we include a guidance in the bis?
Yes this seems worth some guidance in 8407bis.
I can't comment on the NETCONF TCP/UDP client-server documents (I haven't looked at them in a while). Even though I have a strong preference for examples which can be validated, I do realize that in some cases it may be impractical.
Regards,Reshad.
    On Wednesday, October 9, 2024 at 02:06:34 AM EDT, [e-mail] <[e-mail]> wrote:  
 
  
Hi Reshad,
 
  
 
Thanks for the follow-up. However, with my 8407bis editor hat, I’m extracting this specific point:
 
  
 
==
 
> - The examples in appendix A are all based on the groupings. But
> since the groupings will not be used in a stand-alone way, I think
> the examples should illustrate a usage of the groupings. For
> example, the examples could be based on the example YANG modules
> in Appendix B.
 

> 

[Med] We do have a note about the usage here: 

" Note that a
  "grouping" does not define any data nodes in the schema tree; the
  examples illustrated are thus for the ease of understanding."

That's said, we will consider your suggestion further. Thanks.
 
  
 
<RR> Ack. But these examples can't be validated (e.g using yanglint).
 
==
 
  
 
As I said, I’m OK to make the change.
 
  
 
However, I also see a similar approach to the one we followed: e.g., draft-ietf-netconf-tcp-client-server/draft-ietf-netconf-udp-client-server/.. include a note: 
 
  
 
   <!-- The outermost element below doesn't exist in the data model. -->
 
   <!--  It simulates if the "grouping" were a "container" instead.  -->
 
  
 
These examples can’t be validated as well.
 
  
 
Do we need to be consistent in how various I-Ds proceed here? Should we include a guidance in the bis?
 
  
 
Cheers,
 
Med
 
  
 
De : Reshad Rahman <[e-mail]> 
Envoyé : mardi 8 octobre 2024 23:15
À : [e-mail]; BOUCADAIR Mohamed INNOV/NET <[e-mail]>
Cc : [e-mail]; [e-mail]
Objet : Re: Yangdoctors early review of draft-ietf-netmod-schedule-yang-02
 
  
 
Hi Med,
 
  
 
Thanks for the prompt response. Please see inline <RR> (where no explicit response, default is ack).
 
  
 
On Friday, October 4, 2024 at 04:33:51 AM EDT, <[e-mail]> wrote:
 
  
 
  
 
Hi Reshad,

Thank you for the review. 

The diff to track the changes made so far can be found here: https://author-tools.ietf.org/api/iddiff?url_1=https://netmod-wg.github.io/schedule-yang/draft-ietf-netmod-schedule-yang.txt&url_2=https://netmod-wg.github.io/schedule-yang/reshad-review/draft-ietf-netmod-schedule-yang.txt

Please see inline for more context. 

I let my co-authors further comment as appropriate.

Cheers,
Med

> -----Message d'origine-----
> De : Reshad Rahman via Datatracker <[e-mail]>
> Envoyé : jeudi 3 octobre 2024 21:32
> À : [e-mail]
> Cc : [e-mail];[e-mail]
> Objet : Yangdoctors early review of draft-ietf-netmod-schedule-
> yang-02
> 
> 
> Reviewer: Reshad Rahman
> Review result: On the Right Track
> 
> Hi all,
> 
> This is an early YD review of -02.
> 
> - My first impression of the document is that it seems
> unnecessarily big, why all these groupings for something as simple
> as a schedule :-) On further reading, I do now understand the
> reason, all the knobs and belle-and-whistles...

[Med] Great.

The abstract and
> section 3.1 do mention "basic, intermediate and advanced versions
> of recurrence related groupings". But there is no further mention
> of which ones are basic/intermediate/advanced. There is a basic-
> recurrence feature defined but it is not clear whether that is
> meant for only the basic groupings or ... Please consider in
> section 3.3 whether each grouping should be tagged as
> basic/intermediate/advanced and whether the features should be
> defined accordingly.
> 

[Med] Updated the wording to better focus on the modularity approach with groupings varying from basic to advanced (iclandar-like). Made this change in both the abstract and also the main text.

> - 3.1 mentions 2 features basic-recurrence and icalendar-
> recurrence. Is it possible that one or the other recurrence
> feature may be supported for some scheduled items but not for all.
> e.g. both supported for disk backups but only basic-recurrence
> supported for pings to a central controller. When implementing a
> standard (e.g. IETF) YANG, a vendor can use deviations to work
> around that.
> Worth adding some text on this? I am also not sure whether it
> makes sense to have those features.
> 

[Med] The use of one or both in the same module is specific to the context where the groupings are used. This is why we do say the following:

  Implementations may support a basic
  recurrence rule or an advanced one as needed, by declaring different
  features.  Whether only one or both features are supported is
  implementation specific and depend on specific scheduling context.

Please note that we provided an example where both are used.
 

<RR> I did see the example and that is actually what triggered the question.
 
  
 
The example for scheduled backups has this:
          container basic-recurrence-schedules {            if-feature schedule:basic-recurrence-supported;            description              "Basic recurrence schedule specification, only applies when               schedule:basic-recurrence-supported feaure is supported.";            leaf schedule-id {              type string;              description                "The schedule identifier for this recurrence rule.";            }            uses schedule:recurrence;           }             container icalendar-recurrence-schedules {            if-feature schedule:icalendar-recurrence-supported;            description              "Basic recurrence schedule specification, only applies when               schedule:icalendar-recurrence-supported feaure is               supported.";            leaf schedule-id {              type string;              description                "The schedule identifier for this recurrence rule.";            }               uses schedule:icalendar-recurrence;          } 
  
 
Let's say the device has another module for scheduled pings (based on example above):
          container basic-recurrence-ping-schedules {            if-feature schedule:basic-recurrence-supported;            description              "Basic recurrence schedule specification, only applies when               schedule:basic-recurrence-supported feaure is supported.";            leaf schedule-id {              type string;              description                "The schedule identifier for this recurrence rule.";            }            uses schedule:recurrence;           }             container icalendar-recurrence-ping-schedules {            if-feature schedule:icalendar-recurrence-supported;            description              "Basic recurrence schedule specification, only applies when               schedule:icalendar-recurrence-supported feaure is               supported.";            leaf schedule-id {              type string;              description                "The schedule identifier for this recurrence rule.";            }               uses schedule:icalendar-recurrence;          }    <RR> How would the device indicate e.g that it supports icalendar-recurrence-schedules but not icalendar-recurrence-ping-schedules? Not via the feature since both use the same feature in the if-feature statement. And the feature support doesn't depend on the context afaik, it is either supported or not supported. So I think we'd need to define features for where the groupings are used and these features would depend on the features defined in this document?   

> - Section 3.1: the feature names have the -supported suffix. This
> is a personal preference, but I think the "supported" part is
> implied for a feature and not needed in the feature names.
> 

[Med] Works for me. This has also the advantage to shorten them. Thanks.

> - Section 3.2: one-shot is clear but the difference between period
> and recurrence is not.
> 

[Med] The period is similar to one-shot with the exception that it does not disable itself once the scheduled action is terminated. Recurrence is more a schedule that occurs many times (e.g., periodic).
 
  
 <RR> This subtlety, i.e. period v/s recurrence, still escapes me. If recurrence is periodic, then it sounds a lot like "period" :-) If it's clear for everyone, maybe I need to look at the document again... But some text in 3.2 may help. 
  
 

> - Sections 3.3.X, I am not sure why all the other groupings are
> listed. e.g.
> 3.3.1 is about "generic-schedule-params", why list all the other
> groupings in Figure 2?

[Med] This is a zoom on the specific branch of the overall tree in Figure 1. That’s a matter of editing taste to accompany reader in walking through the full tree.


    <RR> Ack. I'll leave that to the RFC Editor.    
>
> - Section 3.3.1, what is the difference between validity and max-
> allowed-end, not clear to me.

[Med] These cover two distinct aspects of activating a schedule (start vs. end). Can you please let me know what is not clear in the following text:

  The "validity" parameter specifies the date and time after which a
  schedule will be considered as invalid.  It determines the latest
  time that a schedule can be executed by a system and takes precedence
  over similar attributes that are provided at the schedule instance
  itself.

And

  The "max-allowed-end" parameter specifies the maximum allowed end
  time of the last occurrence.  A requested schedule will be rejected
  if the end time of last occurrence is later than the configured "max-
  allowed-end" value.

Thanks.


 <RR> What would help confirm my understanding, or not, is an example with both in the appendix. Thanks. 
  
 
>
> - Section 3.3.3, should frequency be frequency-unit? Strictly
> speaking, that's an interval-unit and not a frequency-unit? It
> does seem odd to me to have frequency and interval in the same
> grouping... And not a fan of identities such as "daily",
> "minutely", "secondly": although those are English words I don't
> think they mean what you're trying to convey here. But if you
> rename frequency to interval-unit, you can use "day", "hour",
> "minute", "second" etc for interval-type (renamed from frequency-
> type).
> 

[Med] We use frequency as we are relying upon RFC5545 for these matters.
 <RR> I have 2 problems with this: - RFC5545 is for iCalendar but the use of that definition of frequency has leaked into use-cases not requiring iCalendar - Terminology section mentions iCalendar (RFC5545) but no mention of frequency. Please add it there.    I am not a fan of mixing interval and frequency. But I'll leave it to the WG.    
> - Section 3.3.3 v/s 3.3.4, intuitively from "recurrence" to
> "recurrence-utc" I expected the change to be just wrt use of UTC.
> Consider renaming "recurrence"
> to "recurrence-basic" since it is basic with just a description
> and an interval/frequency.
> 

[Med] Makes sense. Fixed.

> - Wrt UTC, some nodes have "utc" as prefix and others as suffix.
> Be consistent and my preference is for suffix e.g. start-time-utc
> (instead of utc-start-time).

[Med] ACK.

> 
> - Section 3.3.X, be consistent in the names. e.g if UTC uses
> start-time-utc, then 3.3.5 should use start-time (not date-time-
> start).
> 

[Med] ACK.

> - Section 3.3.X, many names have recurrence- as prefix e.g.
> recurrence-first, recurrence-bound, recurrence-description. Best
> practice is to remove the
> recurrence- prefix and put all these nodes in a recurrence
> container. You might to rework the groupings a bit but it should
> be straightforward.

[Med] We are aware about that guidance however we added "recurrence-" for some of the items you mentioned in order to cover cases where, e.g., both period and recurrence are used within the same choice. Please see https://github.com/netmod-wg/schedule-yang/pull/37 where we made that change.



 <RR> The fact that the recurrence- prefix is used for some leaf nodes to me indicates that a recurrence container would be useful.    >  
> - Sections 3.3.4 and 3.3.5, not clear to me why UTC is deemed to
> be for machine readability and with-time-zone for human
> readability.

[Med] You may refer to, e.g.,https://mailarchive.ietf.org/arch/msg/netmod/qJtMJHg1qdgBgKNAKjOFe8z885c/ for systems to manipulate time zones, etc.

> 
> - Section 3.3.4: what happens if duration > interval? I thought I
> saw some text on this but can't find it.
> 

[Med] The behavior will depend on the scheduled action. All what we say right now is to insist on the differences between these two notions:

  Note that the "interval" and "duration" cover two distinct properties
  of a schedule event.  The interval specifies when a schedule will
  occur, combined with the frequency parameter; while the duration
  indicates how long an occurrence will last.

> - recurrence-bound, I don't understand the use of the word "bound"
> here, is it as in "boundary"? Maybe call it limit?
> 

[Med] This is more about limit. FWIW, "bound" was used here as we leverage RFC 5545 where we "grabbed" some naming.
 <RR> I took a look at RFC5545 and it's still not clear. The YANG description here says "Modes to bound the recurrence rule.", still not clear to me. If not "recurrence-limit", what about "recurrence-end", "recurrence-max", may be not ideal but IMO than recurrence-bound.    > - discard-action does not mention how the warning/error message is 
> generated, is it a syslog?

[Med] The exact mechanism to supply these is specific to the context/scheduled action. I'm afraid that mandating a specific mechanism here will limit the reusability of the groupings.

How about using an alarm (RFC8632) as
> another option?
> 

[Med] alarm per 8632 is more a state than an action. No?

  Alarm (the general concept):  An alarm signifies an undesirable state
      in a resource that requires corrective action.
 
  
 <RR> Ack.    
> - I don't see must-statement that period-end > period-start in the
> YANG, although it is mentioned in the text.
> 

[Med] We already considered that among authors but went with the normative language than a must statement because we don't see a simply what to express operations with date-and-time. If you have a suggestion here, we will be pleased to implement it. Thanks. 
 <RR> Ack. 
  
 

> - The examples in appendix A are all based on the groupings. But
> since the groupings will not be used in a stand-alone way, I think
> the examples should illustrate a usage of the groupings. For
> example, the examples could be based on the example YANG modules
> in Appendix B.
 

> 

[Med] We do have a note about the usage here:

" Note that a
  "grouping" does not define any data nodes in the schema tree; the
  examples illustrated are thus for the ease of understanding."

That's said, we will consider your suggestion further. Thanks.
 
  
 
<RR> Ack. But these examples can't be validated (e.g using yanglint).
 
  
 
Regards,
 
Reshad.
____________________________________________________________________________________________________________
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.
 
  
 
  
 
  
 
  
 
  
 
  
 
  
 _________________ ______________________________ ______________________________ ______________________________ _
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.