[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Updating the MIB Review guidelines - my comments part 1
It is close to 1am already and I have not found time to review
the rest of the doc. SOme answers inline
Thanks,
Bert
> -----Original Message-----
> From: C. M. Heard [mailto:heard@pobox.com]
> Sent: maandag 7 juni 2004 18:24
> To: Mreview (E-mail)
> Subject: RE: Updating the MIB Review guidelines - my comments part 1
>
>
> 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.
>
Guess I missed it because it is not listed in ToC.
Normally I think IANA considerations is a ToC entry.
> > 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?
>
As I said, "I wonder". The reason I wonder is because we (at least I) tend
to tell people that they should not talk about "MIB" if they mean a "MIB module"
or a "MIB document". So teh idea was tio try and make that stick betetr.
> > 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.
OK then fine. As long as we understand it will be removed.
> 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.
>
So no need to add more.
> > 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.
>
As I said, I can live with it.
> > 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.
>
Mmm... it seems to be a point though that does not stick well enough with people.
And then there comes the saying: "repetition is the key to learning".
Oh well...
> > 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
>
Sounds fine
> > 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.
>
OK
> > 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).
There is actually debate in IESG if RFC-Editor can just remove such
IANA considerations section. And anyway... we will never know how
policy changes over time. So if possible I like to be silent on it.
But it is just a personal opinion.
> 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.
>
I think it would be better if we could write our text such that 2223bis
is NOT normative. I am not very confident that that doc will come out as
an RFC anytime soon. It has been promised too many times already.
> > 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.
Right, and they will add it. And they can do so based on the text that is
in RFC3667 and 3668. So we should not make ourselves dependent on 2223bis.
Or so is my personal (actaully pretty strong) opinion.
> 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.
>
Mmmm
sect 4.1 says:
It is RECOMMENDED that module names be mnemonic. See Appendix C for
additional suggestions.
sect 4.2 is better in my view with:
See Appendix C for suggested descriptor and TC 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.
>
> 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.
>
I'll let Juergen defend his case.
> > 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).
>
NEW text looks fine to me.
> > 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.
>
SO you ahve reasons why you do what you do. OK
> > 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 understand it is existing practice,
I am bringing it up because it is now discouraged in ID-Checklist.
I told IESG that we do it for MIB modules and that we thought it was
goodness. So they will accept that as an exception (I think).
If we want to keep it, we can and we'll see if IESG barks.
> 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.
>
I had indeed pointed out that all the author info does change so
frequently these days, that between WG sending doc to AD/IESG and
RFC Editor publishing, many email addresses change.
soapbox: this is a nice way of saying that it takes too long :-(
> > 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.
>
Thanks. I can live with it... just want to make sure we all agree.
We can also agree and not write it down so explicitly.
> > 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.
>
It looks as follows:
- For integer-valued enumerations:
- INTEGER is REQUIRED;
- Integer32, Unsigned32, and Gauge32 MUST NOT be used.
Note that RFC 2578 recommends (but does not require) that integer-
valued enumerations start at 1 and be numbered contiguously. This
recommendation SHOULD be followed unless there is a valid reason to
do otherwise, e.g., to match values of external data or to indicate
special cases, and any such special-case usage SHOULD be clearly
documented. For an example see the InetAddressType TC [RFC3291].
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.
- If the value range is between -2147483648..2147483647 (inclusive)
and negative values are possible, then:
So to me it seems that the 2 paragraphs belong to the discussion about
inter-valued enumerations. So I (but this is probably just a matter of
style) would indent them 2 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 also looks right to me. I just ran off a copy without
> any headers or footers to verify that.
>
Same reasoning on my side.
> > That is how far I got, more later
> > Thanks,
> > Bert
>
> OK, thanks, I hope we don't find too much more :-)
>
I suspect I will go to bed now instead of trying to read through the rest
(1am now).
Bert
> Mike
>
>