[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
guidelines changes to date (WAS: comments on mib review guidelines01)
On Mon, 7 Jul 2003, Wijnen, Bert (Bert) wrote:
> Mmm... can you send me a complete rev 02 (ort whatever the curen
> doc is that you have, so I can check latest text).
There is no -02 version yet, just a draft that includes all the
minor corrections that have been sent to me to date (including
Juergen's). I've sent the complete document to you in a private
message, and in this message to the list I've attached a couple of
diffs (one without any context, and one with full context) showing
what these corrections are. Note that change proposals which are
still under discussion are not included.
Mike
*** draft-ietf-ops-mib-review-guidelines-01.txt Mon Feb 24 09:27:55 2003
--- draft-ietf-ops-mib-review-guidelines-XX.txt Sat Jul 5 15:53:12 2003
***************
*** 288 ****
! conjunction with the IF-MIB [RFC2863] and are required to document
--- 288 ----
! conjunction with the IF-MIB [RFC2863] and are REQUIRED to document
***************
*** 292 ****
! configuration and multiplexing of interface sublayers must contain a
--- 292 ----
! configuration and multiplexing of interface sublayers MUST contain a
***************
*** 431 ****
! module that will appear in the published RFC must contain a pointer
--- 431 ----
! module that will appear in the published RFC MUST contain a pointer
***************
*** 773 ****
! possible for such other unusual/irregular events to occur, the the
--- 773 ----
! possible for such other unusual/irregular events to occur, the
***************
*** 780 ****
! of such a discontinuity indicator see the ifCounterDisconuityTime
--- 780 ----
! of such a discontinuity indicator see the
***************
*** 789 ****
! object in the IF-MIB [RFC2863].
--- 789 ----
! ifCounterDiscontinuityTime object in the IF-MIB [RFC2863].
***************
*** 973 ****
! list can be expected to to grow as additional TCs are developed.
--- 973 ----
! list can be expected to grow as additional TCs are developed.
***************
*** 1131,1132 ****
! Complete requirements for the RowStatus and StorageType TCs are can
! be found in RFC 2579, in the DESCRIPTION clauses for those TCs.
--- 1131,1132 ----
! Complete requirements for the RowStatus and StorageType TCs can be
! found in RFC 2579, in the DESCRIPTION clauses for those TCs.
***************
*** 1323 ****
! statement contains the following contains the OBJECT clause (*)
--- 1323 ----
! statement contains the following OBJECT clause (*)
***************
*** 1410 ****
! - The MODULE-IDENTITY invocation must be updated to include
--- 1410 ----
! - The MODULE-IDENTITY invocation MUST be updated to include
***************
*** 1617,1619 ****
! 2434. Note that module itself must be in an appendix that will
! disappear after publication and that the IANA Considerations section
! that will appear in the RFC must contain a pointer to that module.
--- 1617,1619 ----
! 2434. Note that the IANA Considerations section that will appear in
! the RFC MUST contain a pointer to that module.
!
*** draft-ietf-ops-mib-review-guidelines-01.txt Mon Feb 24 09:27:55 2003
--- draft-ietf-ops-mib-review-guidelines-XX.txt Sat Jul 5 15:53:12 2003
***************
*** 285,295 ****
MUST be noted in the overview section, as MUST any special
interpretations of objects in other MIB modules. For instance, so-
called media-specific MIB modules are always implemented in
! conjunction with the IF-MIB [RFC2863] and are required to document
how certain objects in the IF-MIB are used. In addition, media-
specific MIB modules that rely on the ifStackTable [RFC2863] and the
ifInvStackTable [RFC2864] to maintain information regarding
! configuration and multiplexing of interface sublayers must contain a
description of the layering model.
3.3. Definitions Section
--- 285,295 ----
MUST be noted in the overview section, as MUST any special
interpretations of objects in other MIB modules. For instance, so-
called media-specific MIB modules are always implemented in
! conjunction with the IF-MIB [RFC2863] and are REQUIRED to document
how certain objects in the IF-MIB are used. In addition, media-
specific MIB modules that rely on the ifStackTable [RFC2863] and the
ifInvStackTable [RFC2864] to maintain information regarding
! configuration and multiplexing of interface sublayers MUST contain a
description of the layering model.
3.3. Definitions Section
***************
*** 424,438 ****
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 is as follows:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). This version
--- 424,438 ----
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 is as follows:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). This version
***************
*** 769,803 ****
- It is OK to use Counter32/64 for counters that may/will be reset
when the management subsystem is re-initialized or when other
unusual/irregular events occur (e.g., counters maintained on a line
card may be reset when the line card is reset). However, if it is
! possible for such other unusual/irregular events to occur, the the
DESCRIPTION clause MUST state that this is so and MUST describe
those other unusual/irregular events in sufficient detail that it
is possible for a management application to determine whether a
reset has occurred since the last time the counter was polled. The
RECOMMENDED way to do this is to provide a discontinuity indicator
as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example
! of such a discontinuity indicator see the ifCounterDisconuityTime
OPS Area Expires August 2003 [Page 14]
Internet Draft Guidelines for MIB Authors and Reviewers February 2003
! object in the IF-MIB [RFC2863].
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that on a discontinuity the counter
MUST reset to zero or to any other specific value.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that it MUST reset at any specific
time/event (e.g., midnight).
- It is NOT OK for one manager to request the agent to reset the
value of counter(s) to zero, and Counter32/64 is the wrong syntax
for "counters" which regularly reset themselves to zero. For the
latter it is better to define or use textual conventions such as
those in RFC 2493 [RFC2493].
--- 769,803 ----
- It is OK to use Counter32/64 for counters that may/will be reset
when the management subsystem is re-initialized or when other
unusual/irregular events occur (e.g., counters maintained on a line
card may be reset when the line card is reset). However, if it is
! possible for such other unusual/irregular events to occur, the
DESCRIPTION clause MUST state that this is so and MUST describe
those other unusual/irregular events in sufficient detail that it
is possible for a management application to determine whether a
reset has occurred since the last time the counter was polled. The
RECOMMENDED way to do this is to provide a discontinuity indicator
as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example
! of such a discontinuity indicator see the
OPS Area Expires August 2003 [Page 14]
Internet Draft Guidelines for MIB Authors and Reviewers February 2003
! ifCounterDiscontinuityTime object in the IF-MIB [RFC2863].
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that on a discontinuity the counter
MUST reset to zero or to any other specific value.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that it MUST reset at any specific
time/event (e.g., midnight).
- It is NOT OK for one manager to request the agent to reset the
value of counter(s) to zero, and Counter32/64 is the wrong syntax
for "counters" which regularly reset themselves to zero. For the
latter it is better to define or use textual conventions such as
those in RFC 2493 [RFC2493].
***************
*** 965,981 ****
4.6.1.10. Other Data Types
There exist a number of standard TCs that cater to some of the more
common requirements for specialized data types. Some have been
mentioned above, and Appendix D contains a partial list that includes
those plus some others that are a bit more specialized. Note that
there exist many standard TCs that are not mentioned there; that
! list can be expected to to grow as additional TCs are developed.
Whenever a standard TC already conveys the desired semantics, it
SHOULD be used in an object definition instead of the corresponding
base type or a locally-defined TC. This is especially true of the
TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411]
because they are Internet Standards, and so modules that refer to
them will not suffer delay in advancement on the standards track on
account of such references.
--- 965,981 ----
4.6.1.10. Other Data Types
There exist a number of standard TCs that cater to some of the more
common requirements for specialized data types. Some have been
mentioned above, and Appendix D contains a partial list that includes
those plus some others that are a bit more specialized. Note that
there exist many standard TCs that are not mentioned there; that
! list can be expected to grow as additional TCs are developed.
Whenever a standard TC already conveys the desired semantics, it
SHOULD be used in an object definition instead of the corresponding
base type or a locally-defined TC. This is especially true of the
TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411]
because they are Internet Standards, and so modules that refer to
them will not suffer delay in advancement on the standards track on
account of such references.
***************
*** 1130,1133 ****
! Complete requirements for the RowStatus and StorageType TCs are can
! be found in RFC 2579, in the DESCRIPTION clauses for those TCs.
--- 1130,1133 ----
! Complete requirements for the RowStatus and StorageType TCs can be
! found in RFC 2579, in the DESCRIPTION clauses for those TCs.
***************
*** 1314,1332 ****
Sometimes MIB module authors will want to specify that a compliant
implementation needs to support only a subset of the values allowed
by an object's SYNTAX clause. For accessible objects this may be
done either by specifying the required values in an object's
DESCRIPTION clause or by providing an OBJECT clause with a refined
SYNTAX in a compliance statement. The latter method is RECOMMENDED
for most cases, and is REQUIRED if there are multiple compliance
statements with different value subsets required. The DIFFSERV-MIB
[RFC3289] illustrates this point. The diffServMIBFullCompliance
! statement contains the following contains the OBJECT clause (*)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
whereas the diffServMIBReadOnlyCompliance statement contains this:
--- 1314,1332 ----
Sometimes MIB module authors will want to specify that a compliant
implementation needs to support only a subset of the values allowed
by an object's SYNTAX clause. For accessible objects this may be
done either by specifying the required values in an object's
DESCRIPTION clause or by providing an OBJECT clause with a refined
SYNTAX in a compliance statement. The latter method is RECOMMENDED
for most cases, and is REQUIRED if there are multiple compliance
statements with different value subsets required. The DIFFSERV-MIB
[RFC3289] illustrates this point. The diffServMIBFullCompliance
! statement contains the following OBJECT clause (*)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
whereas the diffServMIBReadOnlyCompliance statement contains this:
***************
*** 1405,1415 ****
4.9. Revisions to MIB Modules
RFC 2578 Section 10 specifies general rules that apply any time a MIB
module is revised. Specifically:
! - The MODULE-IDENTITY invocation must be updated to include
information about the revision. In particular, the LAST-UPDATED
clause value MUST be set to the revision time, a REVISION clause
with the same UTC time and an associated DESCRIPTION clause
describing the changes MUST be added, and any obsolete information
in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses
--- 1405,1415 ----
4.9. Revisions to MIB Modules
RFC 2578 Section 10 specifies general rules that apply any time a MIB
module is revised. Specifically:
! - The MODULE-IDENTITY invocation MUST be updated to include
information about the revision. In particular, the LAST-UPDATED
clause value MUST be set to the revision time, a REVISION clause
with the same UTC time and an associated DESCRIPTION clause
describing the changes MUST be added, and any obsolete information
in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses
***************
*** 1614,1622 ****
7.) IANA Considerations Section -- if the draft contains the initial
version of an IANA-maintained module, verify that the MODULE-IDENTITY
invocation contains maintenance instructions that comply with RFC
! 2434. Note that module itself must be in an appendix that will
! disappear after publication and that the IANA Considerations section
! that will appear in the RFC must contain a pointer to that module.
--- 1614,1622 ----
7.) IANA Considerations Section -- if the draft contains the initial
version of an IANA-maintained module, verify that the MODULE-IDENTITY
invocation contains maintenance instructions that comply with RFC
! 2434. Note that the IANA Considerations section that will appear in
! the RFC MUST contain a pointer to that module.
!