RE: Updating the MIB Review guidelines - my comments part 1

["Wijnen, Bert (Bert)" <bwijnen@lucent.com>]

I hope we can get to the point that I can issue a 4 week IETF
Last Call coming Friday morning (European time).

So may I also encourage all MIB doctors to review asap and feedback 
thei rissues/concerns/suggestions.

I started to go over it and have the following commnets, basically 
just nits, but since this is getting ready for BCP, we better put
all the dots on all i's and cross all t's

So here we go:

1. This document should probably set a GOOD example and have its own
   IANA COnsiderations section!?

2. I wonder if in the title should we should s/MIB/MIB Document/ ?
   
3. The ptr to mailing list info on the front page is fine for the I-D.
   Should we recommend RFC-Editor to remove it? I had to change the list
   name recently because of spam. If we want a ptr in RFC, maybe point to
   www.ops.ietf.org web page?

4. Is the first para in sect 2 still needed?
   Seems you have already proper references and all that in sect 1.
   I can live with it though.

5. One but last line on page 6: s/(other those/(other than those/ ??

6. Sect 3.6 should maybe also list that "privacy aspects/risks" must be 
   documented in the security considerations section.

7. Sect 3.7. I wonder if it makes sense to have 3 subsections.
   3.7.1. Documents that create a new name space
   3.7.2. Documents that just need assignments in existing namespace(s)
   3.7.3. Documents that have no iana requests
   This so that people can more quickly find the text they need.

8. Sect 3.7 3rd para.  Should we add OBJECT-IDENTITY ?

9. Sect 3.7 last para.
   Although it is probably such that RFC-Editor will remove an empty IANA
   Considerations section, I wonder if we should recommend that authors/editors
   instruct RFC-Editor to do so or not. Since this still has ongoing discussion
   in various places, why do we not just leave it out and then whenever the
   policy settles, RFC-Editor will know what to do.

10. Sect 3.8 states:
      IETF MIB documents MUST contain the copyright notices and disclaimer
      specified in Section 4.3 of RFC 2223bis [RFC2223bis] and Sections 5.4
      and 5.5 of RFC 3667 [RFC3667].  
    I believe that RFC3667 is the authoritative place. And so I would rather
    see it phrased as follows:
      IETF MIB documents MUST contain the copyright notices and disclaimer
      specified in Sections 5.4 and 5.5 of RFC 3667 [RFC3667].   Note that
      Section 4.3 of RFC 2223bis [RFC2223bis] also states this requirement.
    Or maybe not even talk about 2223bis here at all.

11. 1st para sect 3.8 at end:  s/other those/other than those/ ??

12. Sect 4.1. Might be good to emphasize that app C also has suggestions on
    naming conventions.
    Appendix C does not talk about prefixing non-IETF modules (as Juergen 
    seems to favor very strongly, i.e. IEEE-XXXX-MIB. Did we decide not to
    make such a recommendation? Or do we intentionally stay silent on it.
    I think it might be appropriate in app C to do so if we believe/agree
    that such prefixes make sense.
    Did we ever agree on wanting to have TC modules be of the form XXXX-TC-MIB ??
    If so we should add it.

13. Sect 4.3 The sect title does not allude to the fact that you also talk
    about when/if/hoe to use experimental tree. Should we add that to sect tilte?
    Again, I would want to make it as easy for people to find what they are
    looking for.

14. First bullet in sect 4.5
    Recently there was discussion (and new ID-Checklist has a statement about it)
    that WG names, mailing list info and charter pages" should not be listed
    in RFCs. The reason being that after x years that mailing list will no
    longer exist, neither will the WG.
    So... although I personally like it if the WG name and mlist is mentioned,
    is it still fair to require/recommend that?

15. Mike, you suggest to always assign directly under mib-2 and no longer allow
    (maybe I say it too strong now) to have things like rmon and mpls subtrees
    that we ask IANA to administer.
    I know we had a discussion about this. May I assume that you read consensus
    under the MIB doctors for the text that you now have (Sect 4.5 3rd bullet)?

16. Sect 4.6.1.1
    - I think you want to indent the first 2 paragraphs on page 15 (2 positions
      to the right.
    - I think you want to indent the 3rd and 2nd to last paragraphs of sect
      4.6.1.1  also 2 positions to the right

That is how far I got, more later
Thanks,
Bert 

> -----Original Message-----
> From: C. M. Heard [mailto:heard@pobox.com]
> Sent: maandag 7 juni 2004 07:06
> To: Mreview (E-mail)
> Subject: Re: Updating the MIB Review guidelines
> 
> 
> On Mon, 24 May 2004, C. M. Heard wrote:
> > MIB Doctors --
> > 
> > In the next couple of weeks I plan to issue an update the MIB review
> > guidelines document.  The main reasons for the update are to bring
> > the document into compliance with RFCs 3667 and 3668 (these are the
> > recently-published replacements for RFC 2026 Section 10) and with
> > the latest IESG policies in http://www.ietf.org/ID-Checklist.html,
> > but besides this there are also some things that need to be updated
> > based on experience with the document over the last 9 months.
> > 
> > The purpose of this note is to make a list of the changes that I
> > need to make to draft-ietf-ops-mib-review-guidelines-02.txt.
> > Please let me know if there is something not on the list below that
> > you think needs to be fixed, or if there is something on the list
> > that you do not think should be there.  Once we agree on the list I
> > will circulate proposed text for the ones that are not routine or
> > obvious.  Note that items below are listed in order of appearance in
> > the guidelines draft.
> 
> Included in-line below is the proposed text for each of the
> non-trivial changes that has not already been discussed.  Attached
> is a pre-release copy of the I-D containing those changes.
> 
> Because Bert is going on vacation on 11 June 2004 and would like to
> get the document into IETF Last Call before then, I would like to get
> the updated draft into the repository not later than the close of
> business on 8 June 2004.  So if you have comments to make I would
> appreciate it if you would do so by that time.  If you don't have time
> to do anything meaningful on such short notice, rest assured that
> any comments you make during the last call period will be welcome.
> 
> Here is the list of changes.
> 
> > 1.) Add updated I-D boilerplate & disclaimer, as required by RFC
> > 3667.
> 
> Done.
> 
> > 2.) On the front page direct comments on the document to
> > <ietf-mibs@ops.ietf.org>, since the old mibs list is defunct.
> 
> Done.  Note that the new mailing list name is spelled correctly in the
> draft (i.e., as <ietfmibs@ops.ietf.org>).
> 
> > 3.) In Section 3.2 add a requirement to mention all modules from
> > which items are imported in the overview section.
> 
> Proposed text is discussed in the e-mail thread entitled
> "References in MIB documents for IMPORTed items".
> 
> > 4.) Change all occurrences of http://www.ietf.org/ID-nits.html to
> > http://www.ietf.org/ID-Checklist.html
> 
> Routine edits, details omitted.
> 
> > 5.) Change the instructions for IPR notices in Section 3.4 (and also
> > in Appendix A) to refer to RFC 3667 instead of RFC 2026.
> 
> The above should have said RFC 3668 instead of RFC 3667.  Anyway, here
> are the changes to the text:
> 
> OLD:
> 3.4.  Intellectual Property Section
> 
>    Bullets (A) and (B) in Section 10.4 of RFC 2026 [RFC2026] specify
>    that certain notices regarding intellectual or other 
> property rights
>    appear in all standards-track RFCs.  Verbatim copies of these so-
>    called IPR notices MUST appear in each MIB document that 
> is destined
>    for the standards track.  If proprietary rights are known to be
>    claimed with respect to the technology described in the document,
>    then the notice in bullet (D) MUST also appear in the document.
> 
> NEW:
> 3.4.  Intellectual Property Section
> 
>    Section 5 of RFC 3668 [RFC3668] contains a notice regarding
>    intellectual property rights or other rights that must 
> appear in all
>    IETF RFCs.  A verbatim copy of that notice MUST appear in 
> every IETF
>    MIB document.
> 
> In Appendix A:  MIB Review Checklist
> OLD:
>    4.) IPR Notices -- verify that the draft contains verbatim 
> copies of
>    the IPR notices specified in bullets (A) and (B) and if 
> needed bullet
>    (D) of Section 10.4 of RFC 2026.
> 
> NEW:
>    4.) IPR Notice -- verify that the draft contains a verbatim copy of
>    the IPR notice specified in Section 5 of RFC 3668.
> 
> > 6.) Add some text in Section 3.5 noting that the RFC Editor requires
> > that all references be cited somewhere in the text (this is the main
> > reason for item #3 above;  the alternative of putting citations in
> > the MIB module is something that I don't think we want to
> > encourage).
> 
> Proposed text is discussed in the e-mail thread entitled
> "References in MIB documents for IMPORTed items".
> 
> > 7.) Where [RFC2223bis] is referenced change the section numbers to
> > match the current draft (<draft-rfc-editor-rfc2223bis-07.txt> unless
> > a newer one appears soon).  Affected sections are 3.5, 3.6, and 3.7.
> 
> Done.  The changes are 4.8 -> 4.7f (Section 3.5);  4.9 -> 
> 4.7c (Section
> 3.6);  and 4.10 -> 4.7d (Section 3.7).
> 
> > 8.) Change the IANA Considerations instructions in Section 3.7 to
> > comply with the new policy requiring an IANA Consideridations
> > section even when the only IANA action that is needed is the
> > assignment of the object identifier for the MIB module's
> > MODULE-IDENTITY value.  Note that this was requested by the IANA
> > representative (and is also required by
> > http://www.ietf.org/ID-Checklist.html).
> 
> The proposed updates to Section 3.7 and also to checklist item #7
> in Appendix A were the subject of a separate e-mail thread.
> 
> > 9.) Change the instructions for copyright notices in Section 3.8 to
> > refer to RFC 3668 instead of RFC 2026.
> 
> The above should have said RFC 3667 instead of RFC 3668.  Anyway, here
> are the changes to the text:
> 
> OLD:
> 3.8.  Copyright Notices
> 
>    IETF MIB documents MUST contain the copyright notices specified in
>    Section 4.3 of RFC 2223bis [RFC2223bis] and Section 10.4 Bullet (C)
>    of RFC 2026 [RFC2026].  Authors and reviewers MUST check make sure
>    that the correct year is inserted into these notices.  In addition,
>    the DESCRIPTION clause of the MODULE-IDENTITY invocation 
> of each MIB
>    module that will appear in the published RFC MUST contain a pointer
>    to the copyright notices in the RFC.  A template suitable for
>    inclusion in an Internet Draft, appropriate for MIB modules other
>    those that are to be maintained by the IANA, is as follows:
> 
> NEW:
> 3.8.  Copyright Notices
> 
>    IETF MIB documents MUST contain the copyright notices and 
> disclaimer
>    specified in Section 4.3 of RFC 2223bis [RFC2223bis] and 
> Sections 5.4
>    and 5.5 of RFC 3667 [RFC3667].  Authors and reviewers MUST check to
>    make sure that the correct year is inserted into these notices.  In
>    addition, the DESCRIPTION clause of the MODULE-IDENTITY 
> invocation of
>    each MIB module that will appear in the published RFC MUST 
> contain a
>    pointer to the copyright notices in the RFC.  A template 
> suitable for
>    inclusion in an Internet-Draft, appropriate for MIB modules other
>    those that are to be maintained by the IANA, is as follows:
> 
> > 10.) Add some text to Section 4.5 encouraging people to root their
> > standards-track MIB modules directly under mib-2 or transmission and
> > discouraging them from creating new technology-specific registries
> > for the IANA to maintain.  (The MPLS WG did that and the PWE3 group
> > is to be following in their footsteps, and I think the trend is
> > regrettable.)
> 
> Add to the following paragraph the sentence at the end:
> 
>    - The value assigned to the MODULE-IDENTITY descriptor 
> MUST be unique
>      and (for IETF standards-track MIB modules) SHOULD reside 
> under the
>      mgmt subtree [RFC2578].  Most often it will be an IANA-assigned
>      value directly under mib-2 [RFC2578], although for media-specific
>      MIB modules that extend the IF-MIB [RFC2863] it is 
> customary to use
>      an IANA-assigned value under transmission [RFC2578].  In the past
>      some IETF working groups have made their own assignments from
>      subtrees delegated to them by IANA, but that practice has proven
> +    problematic and is NOT RECOMMENDED.  Also NOT RECOMMENDED is the
> +    practice of setting up another subtree under mib-2 or 
> tranmsission
> +    for the IANA to administer, because it offers no technical
> +    advantage to compensate for the increased administrative 
> workload.
> 
> > 11.) Add some text to Section 4.5 strongly admonishing authors NOT
> > to use misappropriated SMI numbers in drafts.  If early
> > implementations are wanted then experimental numbers should be
> > obtained.
> 
> Add the following pragraph at the end of the section:
> 
>    Note well:  prior to official assignment by the IANA, a draft
>    document MUST use a placeholder (such as "XXX" above) 
> rather than an
>    actual number.  If trial implementations are desired during the
>    development process, then an assignment under the 'experimental'
>    subtree may be obtained from the IANA (cf. Section 4.3).
> 
> > 12.) In Sections 4.6.1.1 and 4.6.1.6 mention that DEFVALS for
> > enumerated INTEGER and BITS objects may, according to the SMI, be
> > specified either by label or by value, but since some tools do not
> > accept the numeric form, the label form is preferred.
> 
> For integer-valued enumerations, add the following paragraph to
> Section 4.6.1.1 just after the paragraph that recommends starting
> integer-valued enumerations at 1:
> 
>    Although the SMI allows DEFVAL clauses for integer-valued
>    enumerations to specify the default value either by label or by
>    numeric value, the label form is preferred since all the 
> examples in
>    RFC 2578 are of that form and some tools do not accept the numeric
>    form.
> 
> For the BITS construct it seems to me, after a close reading of RFC
> 2578, that numeric values are NOT permitted in DEFVAL clauses and so
> there is no need to add any text.  Here is the relevant part of
> RFC 2578.  MIB doctors please speak up if it appears that I have
> misread the document.
> 
>     DefValPart ::= "DEFVAL" "{" Defvalue "}"
>                 | empty
> 
>     Defvalue ::=  -- must be valid for the type specified in
>                   -- SYNTAX clause of same OBJECT-TYPE macro
>                   value(ObjectSyntax)
>                 | "{" BitsValue "}"
> 
>     BitsValue ::= BitNames
>                 | empty
> 
>     BitNames ::=  BitName
>                 | BitNames "," BitName
> 
>     BitName ::= identifier
> 
> > 13.) In Section 4.9 clarify that adding an OBJECT clause specifying
> > support for the original set of values of an enumerated INTEGER or
> > BITS object is needed (to avoid a silent change to the meaning of
> > the compliance statement) only when the MAX-ACCESS is read-write or
> > read-create.
> 
> The above should have said MIN-ACCESS.  Anyway, here are the changes
> to the text:
> 
> OLD:
>    - RFC 2580 should (but does not) recommend that OBJECT clauses
>      specifying support for the original set of values be added to a
>      compliance statement when enumerated INTEGER objects or BITS
>      objects referenced by the compliance statement have enumerations
>      added, assuming that no such clauses are already 
> present.  This is
>      necessary in order to avoid a silent change to the meaning of the
>      compliance statement.  MIB module authors and reviewers SHOULD
>      watch for this to ensure that such OBJECT clauses are added when
>      needed.  Note that this may not always be possible to do, since
>      affected compliance statements may reside in modules 
> other than the
>      one that contains the revised definition(s).
> NEW:
>    - RFC 2580 should (but does not) recommend that an OBJECT clause
>      specifying support for the original set of values be added to a
>      compliance statement when an enumerated INTEGER object or a BITS
>      object referenced by the compliance statement has enumerations or
>      named bits added, assuming that no such clause is already present
>      and that the effective MIN-ACCESS value is read-write or
>      read-create.  This is necessary in order to avoid a silent change
>      to the meaning of the compliance statement.  MIB module 
> authors and
>      reviewers SHOULD watch for this to ensure that such 
> OBJECT clauses
>      are added when needed.  Note that this may not always be possible
>      to do, since affected compliance statements may reside in modules
>      other than the one that contains the revised definition(s).
> 
> > 14.) I am not sure if the issue of module names is clear in
> > guidelines.  My intent was that Appendix C should be considered to
> > be helpful suggestions, not rules that we impose on other people;
> > but the practical effect is that the MIB doctors themselves become
> > bound by these suggestions.  Frankly I don't think that a change is
> > needed, but others might disagree.  Let me know if you do.
> 
> I have not heard any requests to update the text, so Appendix C
> remains unchanged.
> 
> > 15.) Update all references to I-Ds that have turned into RFCs (one
> > good think about the long delay is that most of the referenced I-Ds
> > have in fact been published).  Add RFCs 3667 and 3668 to the
> > normative reference list (and remove RFC 2026 if it is no longer
> > cited after the changes discussed above).
> 
> Done.  Note that the updates do include pointers to the latest
> versions of cited I-Ds (<draft-rfc-editor-rfc2223bis-07.txt>) and
> to I-Ds that are slated to replace two of the informative references
> (<draft-ietf-ops-rfc3291bis-04.txt> and 
> <draft-ietf-entmib-v3-04.txt>).
> 
> > Regards,
> > 
> > Mike
> > 
>