Re: [CCAMP] [yang-doctors] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15

Leeyoung <leeyoung@huawei.com> Tue, 20 November 2018 14:55 UTC

Return-Path: <leeyoung@huawei.com>
X-Original-To: ccamp@ietfa.amsl.com
Delivered-To: ccamp@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 2593B126BED; Tue, 20 Nov 2018 06:55:20 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.599
X-Spam-Level:
X-Spam-Status: No, score=-2.599 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, HK_RANDOM_ENVFROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id BK_RRBhXNvaK; Tue, 20 Nov 2018 06:55:17 -0800 (PST)
Received: from huawei.com (lhrrgout.huawei.com [185.176.76.210]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 58B98129C6A; Tue, 20 Nov 2018 06:55:15 -0800 (PST)
Received: from lhreml702-cah.china.huawei.com (unknown [172.18.7.107]) by Forcepoint Email with ESMTP id 57D875F57D6C6; Tue, 20 Nov 2018 14:55:11 +0000 (GMT)
Received: from SJCEML701-CHM.china.huawei.com (10.208.112.40) by lhreml702-cah.china.huawei.com (10.201.108.43) with Microsoft SMTP Server (TLS) id 14.3.408.0; Tue, 20 Nov 2018 14:55:12 +0000
Received: from SJCEML521-MBX.china.huawei.com ([169.254.1.160]) by SJCEML701-CHM.china.huawei.com ([169.254.3.19]) with mapi id 14.03.0415.000; Tue, 20 Nov 2018 06:55:06 -0800
From: Leeyoung <leeyoung@huawei.com>
To: "Acee Lindem (acee)" <acee@cisco.com>, Ladislav Lhotka <lhotka@nic.cz>, Martin Bjorklund <mbj@tail-f.com>, "yang-doctors@ietf.org" <yang-doctors@ietf.org>, "draft-ietf-ccamp-wson-yang.all@ietf.org" <draft-ietf-ccamp-wson-yang.all@ietf.org>, "ccamp@ietf.org" <ccamp@ietf.org>
Thread-Topic: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15
Thread-Index: AQHUe5eRO5XfTjb910+TwqsYjCqpPaVPdtqAgAAHo4CAAD2dAP//wczggAC1yQCAAWJYEIADM1WAgAJxiNCAAePGAP//q8vw
Date: Tue, 20 Nov 2018 14:55:05 +0000
Message-ID: <7AEB3D6833318045B4AE71C2C87E8E173D096419@sjceml521-mbx.china.huawei.com>
References: <154214436885.27217.10840968131851055732@ietfa.amsl.com> <20181114.092805.2297210793468765876.mbj@tail-f.com> <5d3b00f41d3776923a40e1af18856491a68ae658.camel@nic.cz> <9C26E0EB-83D1-40A3-A643-950B924815A8@cisco.com> <7AEB3D6833318045B4AE71C2C87E8E173D08BF42@sjceml521-mbx.china.huawei.com> <BCC6CBA2-38B9-4D51-B680-88B51DB24302@cisco.com> <7AEB3D6833318045B4AE71C2C87E8E173D08C485@sjceml521-mbx.china.huawei.com> <CDF81F44-5882-4E42-8B14-5D4A59DFEAB2@cisco.com> <7AEB3D6833318045B4AE71C2C87E8E173D0940F6@sjceml521-mbx.china.huawei.com> <0CB731F7-8D67-46B2-9DE9-FD4CB66087B9@cisco.com>
In-Reply-To: <0CB731F7-8D67-46B2-9DE9-FD4CB66087B9@cisco.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
x-originating-ip: [10.192.11.123]
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: base64
MIME-Version: 1.0
X-CFilter-Loop: Reflected
Archived-At: <https://mailarchive.ietf.org/arch/msg/ccamp/UE0u6rJai7IGXMeKqYBN92YO1ZA>
Subject: Re: [CCAMP] [yang-doctors] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15
X-BeenThere: ccamp@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Discussion list for the CCAMP working group <ccamp.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/ccamp>, <mailto:ccamp-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/ccamp/>
List-Post: <mailto:ccamp@ietf.org>
List-Help: <mailto:ccamp-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/ccamp>, <mailto:ccamp-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 20 Nov 2018 14:55:20 -0000

Hi Acee,

Great! I just uploaded the revision (v16). Thanks a lot for your thorough comments and a quick response. 

Thanks,
Young

-----Original Message-----
From: Acee Lindem (acee) [mailto:acee@cisco.com] 
Sent: Tuesday, November 20, 2018 5:55 AM
To: Leeyoung <leeyoung@huawei.com>; Ladislav Lhotka <lhotka@nic.cz>; Martin Bjorklund <mbj@tail-f.com>; yang-doctors@ietf.org; draft-ietf-ccamp-wson-yang.all@ietf.org; ccamp@ietf.org
Subject: Re: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15

Hi Young, 

Thanks for the update. This version looks good. I had actually misinterpreted FEC as MPLS Forwarding Equivalence Class rather than Forward Error Correction ;^) 

Thanks,
Acee

On 11/19/18, 1:07 PM, "Leeyoung" <leeyoung@huawei.com> wrote:

    Hi Acee,
    
    Thanks for your quick reply and pointing out specific acronyms to be expanded. I agree with you on the expansion of the acronyms, which is incorporated in the proposed revision (v16). Please see the attached diff file that compares v15 and v16. I will upload version 16 shortly. Please let me know if there are still issues to be corrected. 
    
    Thanks & Best regards,
    Young
    
    -----Original Message-----
    From: Acee Lindem (acee) [mailto:acee@cisco.com] 
    Sent: Saturday, November 17, 2018 11:45 AM
    To: Leeyoung <leeyoung@huawei.com>; Ladislav Lhotka <lhotka@nic.cz>; Martin Bjorklund <mbj@tail-f.com>; yang-doctors@ietf.org; draft-ietf-ccamp-wson-yang.all@ietf.org
    Subject: Re: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15
    
    Hi Young, 
    
    The changes look good. The one question I have is whether you should expand the optical acronyms on first use in the ietf-layer0-types.yang. Even if they are defined in other documents, the models need to stand on their own. I guess the question is whether anyone using types in the first place would know all these acronyms. I'm talking about TP, TTP, PID, OADW, ROADM, CWDM, DWDM, FEC, G-FEC, E-FEC, ODU, OPU, OTU, OXC, and potentially others. I'll leave it up to you. 
    
    Thanks,
    Acee
    
    On 11/15/18, 8:22 PM, "Leeyoung" <leeyoung@huawei.com> wrote:
    
        Hi Acee,
        
        Please see the diff file between version 15 and version 16. I just wanted to check with you if the revision (v16) satisfies you. I believe I did address all of your comments faithfully and corrected all the nits. But in case there are still issues to resolve, please let me know. Thanks.
        
        Best regards,
        Young
        -----------------------
        The followings are my comments to your comments raised during your Yang doctor review. 
        
        Minor Issues: 
        
              1. The document has 7 authors. This will have to be ok'ed by the 
                 responsible AD. 
        YL>> now 5 authors in the front page.
        
              2. There is no consistency in the usage of periods in the YANG descriptions. 
        
        YL>> removed periods in all YANG descriptions. 
        
              3. The type descriptions in ietf-layer0-types are rather terse and many times
                 just repeat part of the leaf name, e.g., "Section.".  Also, optical domain 
                 abbreviations are not expanded.
        
        YL>> More words in the type descriptions are supplied; expanded some key terms. 
        
              4. The indentation in ietf-layer0-types is not consistent. I tried to fix. 
        
        YL>> Fixed. 
        
              5. When conditions starting with "Augement maximum LSP bandwidth of TE
                 link template" and ending with "Augment unreserved bandwidth of TE
                 link template" in ietf-layer0-types are commented out.
        
        YL>> Commented-out portions are removed. These augmentation statements are augmenting the topology templates for which there is no network-types attributes. In other words, if you follow the path in the when statement you will not go to an existing leaf in the YANG tree. 
        
              6. If the model ietf-wson-topology.yang is rendered, the 
                 "/* .... */" comments would be better served being in the augmentation
                  descriptions rather than in comments. Most of augmentation descriptions
                  currently say "WSON label.". 
        
        YL>> All exterior comments are moved to the augmentation descriptions. 
        
              7. When conditions starting with "Augment label hop of underlay primary path
                 of TE link template" and ending "Augment label restrictions end of TE 
                 link template" in ietf-wson-topology.yang are
                 link template" and ending with "Augment unreserved bandwidth of TE
                 link template" in ietf-layer0-types are commented out.
        
        YL>> See my comment for #5.
         
              8. The descriptions at the module level could contain more information than
                 just a one liner and the copyright.
        
        YL>> Added more detailed text. 
        
              7. The "Security Considerations" section in the draft doesn't follow the 
                 template in https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines
                 and doesn't enummarate the corresponding leaves their delta exposures.
         
        YL>> Supplied. 
        
        Nits:
        
              1. Normally revision description start with the "Initial Version". 
        
        YL>> Corrected. 
        
              2. Changes references to "Yang" to "YANG".
        
        YL>> Corrected. 
        
        In addition, all nits have been fixed. 
        
        
        
        -----Original Message-----
        From: Acee Lindem (acee) [mailto:acee@cisco.com] 
        Sent: Wednesday, November 14, 2018 1:44 PM
        To: Leeyoung <leeyoung@huawei.com>; Ladislav Lhotka <lhotka@nic.cz>; Martin Bjorklund <mbj@tail-f.com>; yang-doctors@ietf.org; draft-ietf-ccamp-wson-yang.all@ietf.org
        Subject: Re: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15
        
        Hi Young, 
        
        This was merely a follow-up Email on a single comment with the other pruned. Did you miss the Email with the complete review (attached)? 
        
        Thanks,
        Aceee
        
        On 11/14/18, 2:33 PM, "Leeyoung" <leeyoung@huawei.com> wrote:
        
            Hi Acee,
            
            Thanks for your YANG Doctor's review on draft-ietf-ccamp-wson-yang-15. 
            
            You said:     
            > Acee Lindem <acee@cisco.com> wrote:
                > >       4. The indentation in ietf-layer0-types is not consistent. I
                > >       tried to fix
            
            I fixed all indentation issues and excessive lines. Here's the updated file attached. Are there any issues with the draft and YANG issues that need to be fixed? 
            
            Thanks.
            Young
            -----Original Message-----
            From: Acee Lindem (acee) [mailto:acee@cisco.com] 
            Sent: Wednesday, November 14, 2018 6:36 AM
            To: Ladislav Lhotka <lhotka@nic.cz>; Martin Bjorklund <mbj@tail-f.com>; yang-doctors@ietf.org; draft-ietf-ccamp-wson-yang.all@ietf.org
            Subject: Re: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15
            
            Martin, Lada,
            
            Thanks - this is useful. Many times I've had to fix models lines during xml2rfc iterations. In fact, I wrote a crude python script to print lines in a file exceeding an input length. 
            
            Thanks,
            Acee 
            
            On 11/14/18, 3:55 AM, "Ladislav Lhotka" <lhotka@nic.cz> wrote:
            
                On Wed, 2018-11-14 at 09:28 +0100, Martin Bjorklund wrote:
                > Hi,
                > 
                > To YANG doctors in general, and the authors of this draft.
                > 
                > 
                > Acee Lindem <acee@cisco.com> wrote:
                > >       4. The indentation in ietf-layer0-types is not consistent. I
                > >       tried to fix.
                > 
                > The RFC editor nowadays tries to enforce consistent indentation and
                > style across all YANG modules published in RFCs.  They ask us to help
                > with this by informing authors.  The RFC editor can run tools and
                > manually fix indentation, but since they don't really know YANG, they
                > prefer that the changes they make are minimal.
                > 
                > The recommendation to authors is to run
                > 
                >   $ pyang --ietf --max-line-length 69 <file>
                > 
                > when this is ok run:
                > 
                >   $ pyang -f yang --keep-comments <file> > <outfile>
                
                Another option is to run
                
                    $ pyang -f yin -o ymod.yin --keep-comments ymod-orig.yang
                
                and then
                
                    $ xsltproc -o ymod.yang yin2yang.xsl ymod.yin
                
                The yin2yang.xsl stylesheet is available here:
                
                https://github.com/llhotka/YANG-I-D/tree/master/.tools/xslt
                
                In my experience, the stylesheet also does a decent job in breaking long lines.
                By default, it tries to break at a space character, another character may be
                suggested by using the "delim" processing instruction.
                
                For example,
                
                    <pattern value="..."><?delim )?></pattern>
                
                instructs the stylesheet to break the argument after a right parenthesis.
                
                Lada
                
                > 
                > Unfortunately, the tool isn't 100% perfect, in that it won't ensure
                > that all lines are short enough.  Specifically, the argument to "path"
                > gets printed on a single line.
                > 
                > So the recommendation is to run this tool, and then manually tweak the
                > long statements, e.g. run
                > 
                >    $ diff <oldfile> <newfile>
                > 
                > to find the diffs.
                > 
                > 
                > 
                > /martin
                > 
                > _______________________________________________
                > yang-doctors mailing list
                > yang-doctors@ietf.org
                > https://www.ietf.org/mailman/listinfo/yang-doctors
                -- 
                Ladislav Lhotka
                Head, CZ.NIC Labs
                PGP Key ID: 0xB8F92B08A9F76C67