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

["C. M. Heard" <heard@pobox.com>]

On Mon, 7 Jun 2004, Wijnen, Bert (Bert) wrote:
> 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 
> their issues/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!?

It does!  It's right after the full copyright statement.  It's
bundled with the other removable sections.

> 2. I wonder if in the title should we should s/MIB/MIB Document/ ?

My preference would be to leave it at is, but I could be talked into
"Guidelines for Authors and Reviewers of MIB Documents" or even
"Guidelines for Authors and Reviewers of IETF MIB Documents".  Note
that with either of these options I would probably leave the footer
as-is because the full title would not fit.

Does anyone else have an opinion?

> 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?

We don't have to tell the RFC Editor to remove that pointer, because it's
in the I-D boilerplate section that gets stripped anyway.  If you want to
have a pointer to http://www.ops.ietf.org/ that's OK, but it would help
if you would make a suggestion on where to put it.  Note that we already
have several pointers to pages on that site.

> 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.

I think so, because the the stuff in Section 1 uses the RFC 2119
terminology to describe what's in other documents.  Here it's
covering the terminology is used in THIS document.  Besides, if
I take it out, someone is sure to ask for it to be put back.

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

Fixed in my nroff source.

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

That's already covered in "Guidelines for a MIB security section" at
http://www.ops.ietf.org/mib-security.html and I would rather not
duplicate it here.

> 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.

Done.  I have taken a little bit of editorial license with the section
headings;  here is how they read:

      3.7 IANA Considerations Section .............................    7
      3.7.1 Documents that Create a New Name Space ................    7
      3.7.2  Documents  that  Require  Assignments  in  Existing
           Namespace(s) ...........................................    8
      3.7.3 Documents with no IANA Requests .......................    9

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

I don't think that's really necessary;  the "will generally
require" language should make it clear that an assignment for
the MODULE-IDENTITY value is only one possibility, and that
covers almost all of the cases I have seen.

> 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.

Current RFC Editor policy is to remove null IANA considerations
sections.  It's true that if the RFC Editor policy changes we'll
have to change the text here.  But if the policy stays as is, I
would prefer to have the instructions exactly as I have written
them, so that authors will know what to expect (and hopefully will
not then to do things such as putting in citations to RFC 2434).
Note that rfc2223bis is a normative reference, and has to precede
this document into the publication queue;  so if there is a change
of policy that requires some adjustment here (or elsewhere), then
we will have a change to get it right before publication.

> 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.

I was about to agree with you, and then I realized that what you said is
not quite true.  RFC2223bis Section 4.3 requires a copyright notice on
the front page of each RFC;  as of this writing, that is still the policy 
of the RFC Editor.  RFC 3667 does not mention a copyright notice for the
front page.  It talks only about the notice and disclosure that appear at
the end and the abbreviated one that goes in a MIB module.

Again, it's possible that RFC Editor policy will change and we will have to
catch up, but we'll have a change to do that before publication because
RFC2223bis is a normative reference and has to be published first.

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

Fixed.

> 12. Sect 4.1. Might be good to emphasize that app C also has suggestions on
>     naming conventions.

It already does this.

>     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.

As the abstract says:

   This memo provides guidelines for authors and reviewers of IETF
   standards-track specifications containing MIB modules.  Applicable
   portions may used as a basis for reviews of other MIB documents.

In other words, guidelines on naming conventions for non-IETF and
non-standards-track MIB modules are out of scope for this document.

>     Did we ever agree on wanting to have TC modules be of the form
>     XXXX-TC-MIB ??
>     If so we should add it.

Proposal:

OLD:
   - The module name should be of the form XXX-MIB, where XXX is a
     unique prefix (usually all caps with hyphens for separators) that
     is not used by any existing IETF MIB module.  For example, the MIB
     module for managing optical interfaces [RFC3591] uses the prefix
     OPT-IF and has module name OPT-IF-MIB. 
NEW:
   - The module name should be of the form XXX-MIB (or XXX-TC-MIB for a
     module with TCs only), where XXX is a unique prefix (usually all
     caps with hyphens for separators) that is not used by any existing
     module.  For example, the module for managing optical interfaces
     [RFC3591] uses the prefix OPT-IF and has module name OPT-IF-MIB.

(I have elided a few words because I would like for this appendix to
fit on a single page).

> 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.

Neither does it allude to when to use the mgmt tree, which we also
talk about

>     Should we add that to sect [title]?
>     Again, I would want to make it as easy for people to find what
>     they are looking for.

I used the same title as in RFC 2578, so that people know where to
find the primary source for all these details.  I would like to
have it this remain as is.

> 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?

I'll do whatever you say.  What's in there now is existing practice.
If we keep it, then ID-Checklist should acknowledge this practice.

I don't have a strong feeling about this, but I would like to point
out that essentially everything in the CONTACT-INFO clause (including
author contact information, and for that matter the Author's Address
in the RFC) suffers from the same problem of volatility.

> 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)?

I'll put out a call on a separate thread.

> 16. Sect 4.6.1.1
>     - I think you want to indent the first 2 paragraphs on page 15
>       (2 positions to the right.

It looks right to me.

>     - 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 also looks right to me.  I just ran off a copy without any headers
or footers to verify that.

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

OK, thanks, I hope we don't find too much more :-)

Mike