1. Requirements

4.4.7 The project manager shall provide a software version description for each software release. 

1.1 Notes

NPR 7150.2, NASA Software Engineering Requirements, does not include any notes for this requirement.

1.2 History

1.3 Applicability Across Classes

Key:    - Applicable | - Not Applicable

2. Rationale

 A software version description document (VDD) is used to identify and record the exact version of software to be delivered to a user, support, or other sites. 

3. Guidance

Software systems and work products undergo multiple builds, reviews, and rebuild cycles before reaching a fully operational state.  Even then, modifications, error corrections, expanded requirements sets, and even code reuse on other projects result in newer versions of the coded product.  The configuration control of these versions, many of which may be used simultaneously on different projects, requires detailed descriptions to assure the correct work is being performed on the released version of interest.

According to ISO/IEC/IEEE 24765:2010 Systems and software engineering--Vocabulary, a version description document is “a document that accompanies and identifies a given version of a system or component ... Typical contents include an inventory of system or parts, identification of changes incorporated into this version, and installation and operating information unique to the version described.”

The Version Description Document (VDD) document is the definitive record of all components of a released software work product, whether it is for internal or external release. The VDD defines a set of dependencies among work products that are part of the complete software release. It describes the contents of a specific software work product release, the methods, and resources needed to re-create the software work product, known changes, uncorrected problems, as well as differences from the prior software release(s). The use of a template for developing the VDD can ease the initial workload required to develop the baseline VDD.  The recommendation for the content of a Software Version Description document is defined in the VDD section of 7.18 - Documentation Guidance in this Handbook.

The VDD includes the scheme for the identification and classification of software item records and information items and their versions, how to establish baselines, and version identification and control. The release record identifies, tracks, and controls a configuration item at the time a version (including the baseline version) is released. A VDD document for each release lists the items being delivered, including system and software item versions, traceability to specifications or previous releases, what has been changed, known problems, and workarounds. It may include installation or delivery instructions unique to the version described. Version information may come from the software architecture, the software detailed design, and/or the source code. Problem information may come from inspections, bug tracking, or the results of static analysis. If a version control system is used, to be effective, it will include the date, time, and size of each software work product. The resulting information from running a checksum algorithm may be included for additional identification and control of the software work product.

Each software release version must have a version number associated with it. A "release" consists of all the components and their associated version numbers. ²⁷⁶ Versioning keeps the changes straight and allows "rollback" to previous versions if a bug is found later in the software life cycle. Versioning is part of software configuration management. It involves archiving the source code and keeping previous versions when a new version is entered into the configuration management system. Because an updated VDD document is released with each version of the software, there may be several VDD documents in circulation if different team members are working on different versions of the software work product. Configuration management and control are necessary for all versions to maintain control and to avoid misinformation.

NASA-specific planning information and resources for the development of the software version description document are available in Software Processes Across NASA (SPAN), accessible to NASA users from the SPAN tab in this Handbook. 

Additional guidance related to the releasing of the VDD may be found in the work products generated by the following related requirement in this Handbook:

4. Small Projects

No additional guidance is available for small projects.

5. Resources

5.1 References

5.2 Tools

6. Lessons Learned

6.1 NASA Lessons Learned

A documented lesson from the NASA Lessons Learned database notes the following:

• Aquarius Reflector Over-Test Incident. Lesson Number 2419 ⁵⁷³:  "The Aquarius reflector was damaged by over-testing during a 2007 test in the JPL acoustic test chamber. The root cause was attributed to a procedural deviation, and the proximate cause was identified as a test control system safing feature that did not activate. This may have been affected by the procedural deviation, but more likely resulted from test control software that had not been updated to the current version. The Aquarius Special Review Board issued a set of recommendations that may help to avoid future over-test incidents ."

6.2 Other Lessons Learned

No other Lessons Learned have currently been identified for this requirement.

7. Software Assurance

7.1 Tasking for Software Assurance

1. Confirm that the project creates a correct software version description for each software release.

2. For each software release, confirm that the software has been scanned for security defects and coding standard compliance and confirm the results.

7.2 Software Assurance Products

• List of any non-conformances (version description corrections, security defects, coding standard non-conformances) added to a tracking system. 

  
  

  Objective Evidence

  •  Software version description data for each software release.
   Definition of objective evidence

  Objective evidence is an unbiased, documented fact showing that an activity was confirmed or performed by the software assurance/safety person(s). The evidence for confirmation of the activity can take any number of different forms, depending on the activity in the task. Examples are:

  • Observations, findings, issues, risks found by the SA/safety person and may be expressed in an audit or checklist record, email, memo or entry into a tracking system (e.g. Risk Log).
  • Meeting minutes with attendance lists or SA meeting notes or assessments of the activities and recorded in the project repository.
  • Status report, email or memo containing statements that confirmation has been performed with date (a checklist of confirmations could be used to record when each confirmation has been done!).
  • Signatures on SA reviewed or witnessed products or activities, or
  • Status report, email or memo containing a short summary of information gained by performing the activity. Some examples of using a “short summary” as objective evidence of a confirmation are:
    • To confirm that: “IV&V Program Execution exists”, the summary might be: IV&V Plan is in draft state. It is expected to be complete by (some date).
    • To confirm that: “Traceability between software requirements and hazards with SW contributions exists”, the summary might be x% of the hazards with software contributions are traced to the requirements.
  • The specific products listed in the Introduction of 8.16 are also objective evidence as well as the examples listed above.

7.3 Metrics

• # of Cybersecurity vulnerabilities and weaknesses identified
• # of Cybersecurity vulnerabilities and weaknesses (Open, Closed, Severity)
• Trending of Open vs. Closed Cybersecurity Non-Conformances over time
• # and type of vulnerabilities and weaknesses identified by the project
• # of Cybersecurity vulnerabilities and weaknesses identified by life-cycle phase
• # of Cybersecurity vulnerabilities and weaknesses identified vs. # resolved during Implementation
• # of Non-Conformances identified in Cybersecurity coding standard compliance (Open, Closed)
• # of planned software requirements implemented in each build vs. # of actual software requirements implemented in each build
• # of software units planned vs. # built
• The number of open non-conformances identified in release documentation, and security/coding standard compliance scans versus # closed non-conformances.
• # of Non-Conformances identified in release documentation (Open, Closed)

7.4 Guidance

Software assurance will confirm that the project maintains a software version description for each software release. Software assurance will check the software version description for correctness and completeness. Topic 7.18 - Documentation Guidance contains a list of what needs to be in a software version description document (VDD). Check to make sure all the items listed are in the release or delivery and that they have the correct version and release numbers. All other materials in the software version description should be present in the release and match the version of the software being released. Typically, if the release is being delivered to an outside group, a physical configuration audit will be done to verify that the documentation and the physical items (software, tools, build instructions, test suites, scripts, etc., and all supporting documentation) match. Software assurance may either perform this audit or participate in it.

Software Assurance also needs to confirm that the software has been scanned for viruses and confirm that no viruses exist in any of the software being released/delivered.

See the software guidance in this requirement for more information on a software version description document VDD - Version Description Document.