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