Subject: [yang-doctors] Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

From: Radek Krejčí <[email-masked]>
Date: Wed, 24 Oct 2018 23:50:22 -0700

Reviewer: Radek Krejčí
Review result: Ready with Nits

This is my YANG-doctor review of draft-ietf-tictoc-1588v2-yang-10. I have
reviewed it mainly from the YANG perspective, since I'm not familiar with IEEE
1588.

The draft as well as the YANG module ietf-ptp@2018-09-10 are in a good shape
and ready to publish. I have only 2, say, editorial notes.

1) email of Rodney Cummings in the module's contact statement misses
(in contrast to emails of other authors) starting ('<') and ending ('>') tags.

2) I don't see any reason for the following paragraph in the appendix A3:

   Under the assumptions of section A.1, the first IEEE 1588 YANG
   module prefix can be the same as the last IETF 1588 YANG module
   prefix (i.e. "ptp"), since the nodes within both YANG modules are
   compatible.

Since the module's prefix is used only locally, it may change when
the module is updated (RFC 7950, sec. 11). So the mentioned paragraph
seems pointless to me (and therefore confusing for readers).

---

From: Jiangyuanlong <[email-masked]>
Date: Thu, 25 Oct 2018 08:19:49 +0000

Hi Radek,

Thanks much for the review.
Please see my comments in the line.

Best regards,
Yuanlong

-----Original Message-----
From: Radek Krejčí [mailto:[email-masked]] 
Sent: Thursday, October 25, 2018 2:50 PM
To: [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Reviewer: Radek Krejčí

This is my YANG-doctor review of draft-ietf-tictoc-1588v2-yang-10. I have reviewed it mainly from the YANG perspective, since I'm not familiar with IEEE 1588.

The draft as well as the YANG module ietf-ptp@2018-09-10 are in a good shape and ready to publish. I have only 2, say, editorial notes.

1) email of Rodney Cummings in the module's contact statement misses (in contrast to emails of other authors) starting ('<') and ending ('>') tags.
[YJ] Good catch, I found this inconsistence too, and we will update it in the next revision.

Since the module's prefix is used only locally, it may change when the module is updated (RFC 7950, sec. 11). So the mentioned paragraph seems pointless to me (and therefore confusing for readers).
[YJ] Good catch, there is a misspelling here, "prefix" should be "postfix" in A.3, it is not the "prefix" statement in the YANG. The logic is, both "ieee1588-ptp" and "ietf-ptp" have a "ptp" postfix.

---

From: Jiangyuanlong <[email-masked]>
Date: Thu, 25 Oct 2018 09:08:37 +0000

Radek,

Sorry that my 2nd comment is not correct.
The module's prefix, i.e., "ptp", is used by other PTP applications (according to RFC7950, the prefix defined by a module SHOULD be used when the module is imported). 
If the same prefix "ptp" is used, these PTP applications don't need to change their YANG codes (i.e., always use the same prefix "ptp" to access PTP nodes), but only change a URN namespace when migrating from IETF to IEEE-1588.
Thus it is more convenient for an implementation to migrate from IETF 1588 YANG to IEEE 1588 YANG.
Since the IETF will transfer the development work of the 1588 YANG to IEEE-1588, it is unlikely that another new 1588 YANG module's prefix will be introduced in the IETF.

Do you have any suggestions to improve the texts?

Thanks,
Yuanlong

-----Original Message-----
From: TICTOC [mailto:[email-masked]] On Behalf Of Jiangyuanlong
Sent: Thursday, October 25, 2018 4:20 PM
To: Radek Krejčí <[email-masked]>; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: [TICTOC] Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Hi Radek,

Best regards,
Yuanlong

-----Original Message-----
From: Radek Krejčí [mailto:[email-masked]] 
Sent: Thursday, October 25, 2018 2:50 PM
To: [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Reviewer: Radek Krejčí

_______________________________________________
TICTOC mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/tictoc

---

From: Radek Krejčí <[email-masked]>
Date: Thu, 25 Oct 2018 16:16:02 +0200

Hi Yuanlong,
let me clarify it - so, we are talking about the YANG module's prefix, right? And "used by other PTP applications" means imported in some other YANG module, right? Then the prefix connected with such an import is arbitrary and it is scoped only to the YANG module where the ptp module is imported. So even if the prefix in the ptp module changes, the modules which imports ptp module does not need to change the prefix they use for the ptp import. I agree, that it is always better when the prefixes matches (and yes, RFC says SHOULD be the same), I'm just saying that it is not a problem when they don't (implementation must be able to handle it because of possible collisions).

The reason why the text seems weird to me is because it does not make sense to me that preserving the prefix is possible because (this is how I understand the paragraph, maybe wrongly) the nodes within the modules are compatible. RFC 7950 allow me to change or preserve the prefix despite the compatibility of the nodes. So what about the following text?

OLD

NEW

   Under the assumptions of section A.1, it will be useful and
   convenient for other YANG modules using 1588 YANG module to keep
   the module prefix of the first IEEE 1588 YANG modules same as in
   the last IETF 1588 YANG module (i.e. "ptp").

Regards,
Radek

---

From: Rodney Cummings <[email-masked]>
Date: Thu, 25 Oct 2018 14:41:04 +0000

Yuanlong,

Radek is referring to:
	     prefix "ptp";

I agree with his comment. We can remove the paragraph that he quotes in 2).

Rodney

> From: Jiangyuanlong <[email-masked]>
> Sent: Thursday, October 25, 2018 3:20 AM
> Subject: RE: Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10
> 
> Hi Radek,
> 
> reviewed it mainly from the YANG perspective, since I'm not familiar with
> IEEE 1588.
> 
> The draft as well as the YANG module ietf-ptp@2018-09-10 are in a good
> shape and ready to publish. I have only 2, say, editorial notes.
> 
> 1) email of Rodney Cummings in the module's contact statement misses (in
> contrast to emails of other authors) starting ('<') and ending ('>') tags.
> Since the module's prefix is used only locally, it may change when the
> module is updated (RFC 7950, sec. 11). So the mentioned paragraph seems
> pointless to me (and therefore confusing for readers).
> [YJ] Good catch, there is a misspelling here, "prefix" should be "postfix"
> in A.3, it is not the "prefix" statement in the YANG. The logic is, both
> "ieee1588-ptp" and "ietf-ptp" have a "ptp" postfix.

---

From: Jiangyuanlong <[email-masked]>
Date: Fri, 26 Oct 2018 03:34:44 +0000

Dear Radek,

Thanks for the clarification and the good suggestion. Yes, your capture is right, and your texts are also correct basically. Though I think the focus in the texts is "other YANG modules", not a target for our standardization.

To emphasize that the first IEEE 1588 YANG is the primary subject, how about rephrase your texts into the following new texts?
NEW

   Under the assumptions of section A.1, the first IEEE 1588 YANG
   module's prefix will be the same as the last IETF 1588 YANG module's
   prefix (i.e. "ptp"). Consequently, it is convenient for other YANG
   modules to use the same default module prefix "ptp" to access PTP
   nodes during the migration from the last IETF 1588 YANG module to
   the first IEEE 1588 YANG module.

Any concerns or other suggestions?

Kind regards,
Yuanlong

-----Original Message-----
From: Radek Krejčí [mailto:[email-masked]] 
Sent: Thursday, October 25, 2018 10:16 PM
To: Jiangyuanlong <[email-masked]>; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Hi Yuanlong,

OLD

NEW

Regards,
Radek

---

From: Radek Krejčí <[email-masked]>
Date: Fri, 26 Oct 2018 08:59:55 +0200

Hi Yuanlong,
just a minor change:

   Under the assumptions of section A.1, the first IEEE 1588 YANG
   module's prefix will be the same as the last IETF 1588 YANG module's
   prefix (i.e. "ptp"). Consequently, other YANG modules can preserve
   the same import prefix "ptp" to access PTP nodes during the migration
   from the last IETF 1588 YANG module to the first IEEE 1588 YANG module.

What do you think?

Regards,
Radek

---

From: Jiangyuanlong <[email-masked]>
Date: Fri, 26 Oct 2018 07:21:01 +0000

Redek,

Thanks a lot for the enhancement. The new texts are accurate for me. We will reflect it in the next revision if there is no other opinion.

Cheers,
Yuanlong

-----Original Message-----
From: Radek Krejčí [mailto:[email-masked]] 
Sent: Friday, October 26, 2018 3:00 PM
To: Jiangyuanlong <[email-masked]>; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Hi Yuanlong,
just a minor change:

What do you think?

Regards,
Radek

---

From: Alex Campbell <[email-masked]>
Date: Sun, 28 Oct 2018 22:06:30 +0000

Radek's original comment still seems to apply here.

Other modules can import this module using whatever prefix they like.
It doesn't have to be the same as the one defined in the module - that is just a convention to minimize any potential confusion.

ieee1588-ptp could specify a "ieee1588" prefix, for example, and other modules would still be free to import it using the "ptp" prefix.

________________________________________
From: TICTOC <[email-masked]> on behalf of Radek Krejčí <[email-masked]>
Sent: Friday, 26 October 2018 7:59 p.m.
To: Jiangyuanlong; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: [TICTOC] Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Hi Yuanlong,
just a minor change:

What do you think?

Regards,
Radek

---

From: Jiangyuanlong <[email-masked]>
Date: Mon, 29 Oct 2018 08:27:07 +0000

Hi Alex, 

We all agree with what Radek's said. The issue is, what shall we include in the appendix A.3 of this document?
There are two options in consideration:
1. admit that ieee1588-ptp could specify whatever prefix, such as "ieee1588" prefix, and other modules in migration can import it using the original "ptp" prefix. 
In this case, we don't need to say anything on the prefix of ieee1588 YANG as there is no suggestion on it. As a result, we can remove the whole paragraph.
However, a totally new module importing ieee1588-ptp will most likely use the new default import prefix "ieee1588", thus implementations will diverge along the road (i.e., some use "ptp", and some use "ieee1588" as in the example).

2. suggest that ieee1588-ptp still use the same "ptp" prefix, and other modules in migration can still import it using the original "ptp" prefix.
In this case, a totally new module importing ieee1588-ptp will most likely use the default import prefix "ptp", thus it is consistent with the above migration case.
This is also aligned with the statement in RFC7950 that "the prefix defined by a module SHOULD be used when the module is imported".

It seems to me option 2 is slightly better. But I will be glad to see more opinions on this topic.

Thanks,
Yuanlong

-----Original Message-----
From: Alex Campbell [mailto:[email-masked]] 
Sent: Monday, October 29, 2018 6:07 AM
To: Radek Krejčí <[email-masked]>; Jiangyuanlong <[email-masked]>; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: [TICTOC] Yangdoctors early review of draft-ietf-tictoc-1588v2-yang-10

Hi Yuanlong,
just a minor change:

What do you think?

Regards,
Radek

---

From: Radek Krejčí <[email-masked]>
Date: Mon, 29 Oct 2018 09:58:05 +0100

I agree. The reason of the statement in RFC7950 is to increase human readability of the YANG modules. It has nothing to do with technical limitations of YANG implementations - 1) the scope of the prefix is only for the importing module itself (it is not the XML prefix used for data) and 2) implementations must be prepared for the case of prefix collision when it cannot be the same as the prefix of the imported module.

I believe that both mentioned ways are fine, but the second one is better.

Regards,
Radek