1. Requirements

5.2.8.1 The Software Version Description shall identify and provide: (SWE-116)

a. Full identification of the system and software (e.g., numbers, titles, abbreviations, version numbers, and release numbers).
b. Executable software (e.g., batch files, command files, data files, or other software needed to install the software on its target computer).
c. Software life-cycle data that defines the software product.
d. Archive and release data.
e. Instructions for building the executable software, including, for example, the instructions and data for compiling and linking and the procedures used for software recovery, software regeneration, testing, or modification.
f. Data integrity checks for the executable object code and source code.
g. Software product files (any files needed to install, build, operate, and maintain the software).
h. Open change requests and or problem reports, including any workarounds.
i. Change requests and/or problem reports implemented in the current software version since the last Software Version Description was published.

1.1 Notes

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

1.2 Applicability Across Classes

Classes C through E and Safety Critical are labeled with "P (Center)" and "SO." "P (Center)" means that an approved Center-defined process that meets a non-empty subset of the full requirement can be used to achieve this requirement.  "SO" means that the requirement applies only for safety-critical portions of the software.

Classes C and D and Not Safety Critical are labeled with "P (Center)." This means that an approved Center-defined process that meets a non-empty subset of the full requirement can be used to achieve this requirement. 

Class F and Class G are labeled with "X (not OTS)."  This means that this requirement does not apply to off-the-shelf software for these classes.

2. Rationale

In accordance with section 5.2.8 of NPR 7150.2, "The Software Version Description identifies and describes a software version consisting of one or more CSCI (Computer Software Configuration Item) s (including any open source software). The software version description (SVD) document is used to release, track, and control a software version." In the event that a project needs to analyze an event that happened in the past, an SVD is a concise record of the software that was delivered and executed.

The precision and completeness of the data entries called for in the required content assure that the correct software is made available and used in its intended application, whether it is being released to other software team members, testing, integration, or production. The SVD facilitates product implementation, testing, operations, and maintenance.

3. Guidance

The SVD is the definitive record of all components of a released software work product, whether it is for internal or external release. The SVD defines a set of dependencies among work products that are part of the complete software release. It provides a description of the contents of a specific software work product release, the methods and resources needed to recreate the software work product, known changes, uncorrected problems, as well as differences from the prior software release(s).

Version information may come from the source code. Problem information may come from bug tracking or the results of static analysis. If a version control system is used, it typically includes the date, time, and size of each software work product.

The SVD includes a 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. An SVD may consist of one or more types of software items. It lists 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. Because an SVD document is released with each version of the software, there may be several SVD 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. See the lessons learned for an example of when configurations were not properly managed.

Below are descriptions of the required content for the SVD for class A and class B software, along with examples and guidance for each. Section 1.2 above presents the approaches to consider for the remaining classes of software.

• Full identification of the system and software.
  • Include identification numbers, titles, abbreviations, version number(s), release number(s).
  • Identify intended recipients (source code might not be released to all participants).
• Executable software.
  • Include identification numbers, titles, abbreviations, version number(s), release number(s).
  • Identify target computer, files, source code.
  • Identify any needed executable software necessary to install the software work product release.
  • Include version descriptions for systems, CSCIs, etc., to the lowest configuration management unit.
  • List any security and/or privacy considerations.
• Software life-cycle data that defines the software product.
  • Requirements: what is satisfied by the release of the software?
  • Design: what design documents are fulfilled by the release of the software?
  • Test:  test documents used during the software verification.
  • Configuration: maintenance and reproduction documents.
  • User: manuals for installing and using the released software.
  • Management: governing development plans for the software.
  • Quality: plans and procedures used to assure the quality of the software.
• Archive and release data.
  • Include identification numbers, titles, abbreviations, version number(s), release number(s) in documents describing the software and the associated life-cycle data.
  • Version control system and archival location information.
• Instructions for building the executable software.
  • Minimum system requirements and needed user environment.
  • Installation instructions applicable to the version release.
  • Identification of other changes still required to make the code usable.
  • Security, privacy, and safety precautions, if any.
  • Installation verification procedures.
  • Details needed to build the executable software.
    • Instructions and data for compiling and linking.
    • Procedures for software recovery, software regeneration, testing, or modification.
• Data integrity checks for the executable object code and source code.
  • Applicable security and privacy considerations.
  • Handling procedures and safeguards.
• Software product files.
  • Files needed to install, build, operate, and maintain the software work product.
• Open change requests and/or problem reports, including any workarounds.
  • Identify known errors or updates not yet installed for the current release.
  • Identify instructions or workarounds for handling these software work product deficiencies.
  • Document change request listings.
  • List known waivers that were approved.
  • List summarized effects of these waivers on the release version's operation and performance.
• Change requests and/or problem reports.
  • Describe the completed changes and their impact on performance and operation.
  • Identify known unsupported requirements for the current release version.
  • Describe interfaces to other software impacted by this version.
  • Identify changes affecting only the current version.

Additional guidance related to the content for the SVD may be found in the work products generated by the following related requirements in this Handbook:

4. Small Projects

This requirement applies equally to all projects, regardless of size. The project's software configuration management system can assist the developer in identifying software products and documentation that belong to a particular release.

5. Resources

5.1 Tools

Tools to aid in compliance with this SWE, if any, may be found in the Tools Library in the NASA Engineering Network (NEN).

NASA users find this in the Tools Library in the Software Processes Across NASA (SPAN) site of the Software Engineering Community in NEN.

The list is informational only and does not represent an “approved tool list”, nor does it represent an endorsement of any particular tool. The purpose is to provide examples of tools being used across the Agency and to help projects and centers decide what tools to consider.

6. Lessons Learned

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

Take Configuration Management (CM) Measures to Control the Renaming and Reuse of Old Command Files. Lesson Number 1481: The Mars Odyssey mission ran into a version control issue when they discovered an improperly named file call script. It was determined that the team had taken an old Mars Global surveyor file to reuse. The file was renamed, but its code creation time captured in the header was not changed. This caused the system to label the file as an old file. As a result, the operations team had to manually specify the correct file to use, until subsequent code fixes were implemented. ⁵⁵⁶