CERT Secure Coding

Space shortcuts

Page tree

In the event a guideline becomes obsolete, it is clearly marked as deprecated at the top of the guideline, and the label "deprecated" is added to the page. If the guideline has been superseded, the superseding guidelines are listed in the deprecation message. Additionally, the date of deprecation and current publication cycle are displayed in the deprecation message. The deprecation message should use the format in the following example (if it has not been superseded by another guideline, some text will look different):

Deprecated

This guideline has been deprecated. It has been superseded by:

07/01/2013 -- Version 1.0

When a guideline is deprecated, it remains available until the next major release, at which point it is moved to the VOID section. This allows the community and tool vendors time to react to the changing guidelines in the Wiki.

When moving a guideline to the VOID section,

  • Add the void label
  • Prefix the title with "VOID" but keep the SEI CERT guideline ID and the rest of the original title (e.g., the new title becomes "VOID INT02-C. Understand integer conversion rules").
  • If a guideline ID (e.g., "INT02-C" in the example above) has already been voided, add the number of the latest voiding after the word "VOID" in the title (e.g., for the third voiding, the new title becomes "VOID #3 INT02-C. Understand integer conversion rules").

Use the Move command, which is available at the top right of the page in the Page View mode.
Revise the 'Deprecated' note so it instead says 'Void', and add the date the rule became void. Below is an example:

 

Void

This guideline has been voided. It has been superseded by

Date deprecated: 07/01/2013 -- Version 1.0

Date voided: 05/01/2014

 Deprecated or voided guideline IDs should not be re-used for a different guideline.

  

 

9 Comments

  1. Robert Seacord

    It is unclear what the current publication cycle would be.  I would think any rule deprecated now would be deprecated in the 1st Edition.

    I also think that when we publish the second edition, deprecated guidelines will be eliminated from the coding standard (and moved to the Void).  The amount of time this affords varies on how long the guideline has been marked as deprecated, but this has parrallels in standard activities.  For example, gets() was deprecated in C99 TC3 and then, in short order, removed from C11.

    1. Aaron Ballman

      Hmm, I was thinking "current" as "what's yet to be published."  Eg) 1st is published already and is fixed, we're working on 2nd (which is when the rule gets deprecated), and the rule will move to the VOID during the cycle for the 3rd (preferably early on).

      1. David Svoboda

        The problem with voiding deprecated rules is that the rules may still be useful to people with old compilers. (Remember our current MSC02-C debate wrt compilers that only support C90.) This won't apply to all deprecated rules, but rules that are still valid for old versions of C should not be voided.

        1. Aaron Ballman

          Perhaps it would make sense to have different deprecations?  Eg)

           

          This rule is deprecated because we wrote two other rules that cover it.  It gets VOIDed

          That rule is deprecated because C11 deprecated the functionality.  It gets moved to something other than VOID (like C90 Rules)

          1. David Svoboda

            Sounds like a good plan. I'll suggest that we not try to pigeonhole deprecations for now...just say "this rule is deprecated because..." and when we do the release we can see why we deprecated things and categorize them then.

      2. Robert Seacord (Manager)

        I think I would like to model this after the ISO/IEC process, except of course we can move more quickly.  I think would deprecate things on the wiki for the existing release, but then when the next edition comes out we would make these changes official and produce a history of what has changed from the previous version. 

        1. Aaron Ballman

          So instead of using the current version being worked on in the message, we use the previous publication version.  So it's sort of a "deprecated since" concept?  And then when the current version being worked on heads out to publication, we still print with the deprecated message?

          1. Robert Seacord

            I'm thinking of it as a "deprecated in".  For example, in the ISO/IEC process, the committee will release "technical corrigendum" which modify the released version of the standard, which are a roll up of defect reports processed by the committee.  Our process is sort of the same, except less formal, and the changes are made immediately and directly to the baseline document.  When we release the second version, I think we will finalize these changes and just provide a history of what has changed since the previous version (e.g., rules which have been renamed or deleted. 

            If this is the process, we probably don't need to label the version the guideline was deprecated in as it will always be the current version.  The date doesn't server much purpose either, except to let people know how guilty they should feel for not catching up or how guitly we should feel about not giving sufficient notice.  This information will also be contained in the history for each page, of course.

            At some point, we'll presumably need to have a functionality freeze on the new version and then remove or clean up the deprecated rules in anticipation of releasing the second version/edition of the standard.

            1. Aaron Ballman

              The impression I got from John Benito's email was that it would be beneficial to users and vendors for us to publish with the deprecations available.  Eg) we publish v1, while making v2 we deprecate some rules, we publish v2 with the rules clearly deprecated.  While making v3, we remove v1's deprecations.  Wash, rinse, repeat.

              I get the impression (and may be wrong) that you want to publish v1, while making v2 we deprecate some rules, and we publish v2 without the deprecations.

              Which approach we take will probably determine what information is of value in the message.  I lean towards Option 1, personally.