1. Minimum Recommended Content

Minimum recommended content for the Version Description Document. 

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.

j. Confirmation that the software has been scanned for security defects and coding standard compliance. 

2. Rationale

The Version Description Document (VDD) identifies and describes a software version consisting of one or more computer software configuration items (CSCI) (including any open source software). The software version description 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 VDD is a concise record of the software that was delivered and executed.

The precision and completeness of the data entries called for in the recommended 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 VDD facilitates product implementation, testing, operations, and maintenance.

3. Guidance

The VDD 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 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 VDD 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 VDD 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 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. See the lessons learned for an example of when configurations were not properly managed. See also SWE-063 - Release Version Description, SWE-077 - Deliver Software Products, SWE-085 - Release Management. SWE-040 - Access to Software Products, SWE-046 - Supplier Software Schedule, SWE-075 - Plan Operations, Maintenance, Retirement, SWE-082 - Authorizing Changes, 

3.1 VDD For Class A and B Software Products

Below are descriptions of the recommended content for the VDD for class A and class B software, along with examples and guidance for each.

• Full identification of the system and software.

• Include identification numbers, titles, abbreviations, version number(s), and 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), and release number(s).

• Identify the target computer, files, and 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), and 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.
  • Instructions and data for compiling and linking.
  • Procedures for software recovery, software regeneration, testing, or modification.
• 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.
• 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.

3.2 Additional Guidance

Links to Additional Guidance materials for this subject have been compiled in the Relevant Links table. Click here to see the Additional Guidance in the Resources tab.

4. Small Projects

Use of a software version description 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 References

5.2 Tools

5.3 Additional Guidance

Additional guidance related to this requirement may be found in the following materials in this Handbook:

5.4 Center Process Asset Libraries

See the following link(s) in SPAN for process assets from contributing Centers (NASA Only). 

6. Lessons Learned

6.1 NASA Lessons Learned

• Take 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.

6.2 Other Lessons Learned

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