- 1. Minimum Recommended Content
- 2. Rationale
- 3. Guidance
- 4. Small Projects
- 5. Resources
- 6. Lessons Learned
Return to 7.18 - Documentation Guidance
1. Minimum Recommended Content
- Identification of the software item.
- Description of the problem or change to enable problem resolution or justification for and the nature of the change, including: assumptions/constraints and change to correct software error.
- Originator of Software Change Request/Problem Report and originator's assessment of priority/severity.
- Description of the corrective action taken to resolve the reported problem or analysis and evaluation of the change or problem, changed software configuration item, schedules, cost, products, or test.
- Life-cycle phase in which problem was discovered or in which change was requested.
- Approval or disapproval of Software Change Request/Problem Report.
- Verification of the implementation and release of modified system.
- Date problem discovered.
- Status of problem.
- Identify any safety-related aspects/considerations/impacts associated with the proposed change and/or identified problem.
- Configuration of system and software when problem is identified (e.g., system/software configuration identifier or list of components and their versions).
- Any workaround to the problem that can be used while a change is being developed or tested.
The Software Change Request/Problem Report provides a means for identifying and recording the resolution to software anomalous behavior, process non-compliance with plans and standards, and deficiencies in life-cycle data or for identifying and recording the implementation of a change or modification in a software item.
Using standard formats for capturing requests for changes and problems found with software allows review boards (e.g., Change Control Boards or Configuration Control Boards) to have a standard format for reviewing and dispositioning the requests/reports. Including required content in these standard formats also helps capture the important information needed to review and resolve the documented change or problem. Capturing descriptions, dates, and corrective actions provides for a complete picture of the request, its resolution, and its progress (for tracking purposes). This information can be critical to project management. Some captured information may also allow for trending (life-cycle phase), estimation of future efforts (date found, date resolved) for similar issues, and lessons learned.
"Discrepancy Reports (DR) and Problem Reports (PR) contain a description of each problem encountered, recommended solutions, and the final disposition of the problem." This is typically minimal content for a change request or problem report. Recommended content is intended to capture:
- Information that describes what needs to be changed and why.
- Information necessary to process the request, e.g., by a Change Control Board or Configuration Control Board (CCB).
- Information needed to authorize the change.
- Information needed to determine the impact and necessity of the change.
For contracted software development, required problem report/change request content needs to be included in any contract or Memorandum of Agreement/Memorandum of Understanding (MOA/MOU) so that contractors (providers) capture the required information in their reporting systems.
Projects may choose to use change tracking, change management, problem reporting, or other tools to capture and manage change requests and problem reports to closure (see SWE-080). These tools may also facilitate metrics capture and trending. Most tools allow some type of customization such that the project's required information can be captured and managed within the tool. Projects may want to prepopulate fields using defined choices or example text to ensure only allowable values are chosen. When choosing a change request or problem report tool, consider the information that must be captured and the ability of the tool to collect or be configured to collect that information.
If a tool is not used, a project may want to capture in the appropriate project documentation project-defined choices for change request/problem report fields that lend themselves to defined lists. This practice limits field content to acceptable project values and helps ensure change request/problem report uniformity.
Guidance for individual elements of the recommended change request/problem report content is included below:
Identification of the software item – name and version of configuration item (code module, document, test, or other item).
Description of the problem or change to enable problem resolution or justification for and the nature of the change, including assumptions/constraints and change to correct software error – description of the problem, including steps to reproduce the issue, data entered, expected results, actual results, what the user sees or experiences; need for the requested change, including relevant details to explain the reason for the change.
Originator of Software Change Request/Problem Report – originator's name, organization, and contact information.
Originator's assessment of priority/severity – originator's opinion regarding urgency of the problem or requested change; may not be the same as the development organization's assessment since originator and developer have different perspectives; may be one of high, major, low, or any other defined criteria that can be used to classify the request/report.
Description of the corrective action taken to resolve the reported problem or analysis and evaluation of the change or problem, changed software configuration item, schedules, cost, products, or test – description of the changes made to address the change request or problem report; description of any associated problem analysis, such as an impact analysis; list of changed configuration items, including code modules, test documentation, requirements, design, and other project documents.
Life-cycle phase in which problem was discovered or in which change was requested – for example, Phase B (Preliminary Design), Phase E (Operations & Sustainment); or requirements, design, development/implementation, integration test, etc.
Approval or disapproval of Software Change Request/Problem Report – disposition of the request/report, typically from a configuration control board (CCB); additional details such as urgency category, disposition date, priority (high, medium, low), severity (inconvenience, halts operation, safety issue, security issue), comments.
Verification of the implementation and release of modified system – unit, integration, system tests run to verify the change and their respective results; test witnesses, if appropriate; name of verifier; date of verification; released software version that contains the change; release date.
Date problem discovered – date of request or date when problem first surfaced.
Status of problem – current status of the change request/problem report using predefined status values such as new, analysis, assigned, implemented, tested, closed; will change as the request is processed and the problem or change is addressed and moved to resolution; could include status change date for tracking purposes.
Identify any safety-related aspects/considerations/impacts associated with the proposed change and/or identified problem – description of features, effects, impacts, behavior, or other factors related to or which affect or could affect the safety of the software or system.
Configuration of system and software when problem is identified, e.g., system/software configuration identifier or list of components and their versions – software version, system configuration/setup, installed options/components, hardware configuration; when dealing with embedded system development, capture board serial numbers, FPGA (Field Programmable Gate Array) version numbers, simulator version numbers, etc.; when developing for PCs, important configuration information includes brand/make, ancillary cards, and drivers installed.
Any workaround to the problem that can be used while a change is being developed or tested – steps to keep system functioning without triggering the problem while the problem is addressed and corrected.
Additional information may be captured based on project needs, tracking requirements, data for metrics, or other reasons. Sample information includes:
- Change request/problem report number/identifier; unique identifier.
- Brief title or description for the request/report.
- Date entered - date report submitted; may not be same as date problem discovered.
- Project name or identifier, if change request/problem reports for multiple projects are captured in a single tool.
- Requirements statement, if request is for enhancement.
- Attempts to repeat the problem (not typical for customer-entered reports but expected for testers).
- Witnesses, observers (may be able to provide analysis data from their perspective).
- Attachments – additional explanatory data such as test data or results.
- Additional comments.
- Detailed analysis data, e.g., analysis effort, recommendation, analyst name, completion date, analysis text, root cause (problem reports only).
- Assigned developer.
- Effort spent designing, implementing, testing the change or correction.
- Type of change: logic, interface, data, computation, or other defined change category.
- Lines of code (LOC) affected by the change.
- Affected baseline: functional, allocated, product.
- Date completed.
Additional guidance related to the content of change requests/problem reports may be found in the following related requirements in this Handbook:
Track and Evaluate Changes
4. Small Projects
Projects with limited budgets may consider using simple tools such as document templates (MS Word) to capture change requests/problem reports and spreadsheets or simple databases for tracking and metrics generation. Another option is to determine if any tools are available at the Center level or from previous projects that can be used at no or low cost to the current project.
(SWEREF-343)STEP Level 2 Software Configuration Management and Data Management course, SMA-SA-WBT-204, SATERN (need user account to access SATERN courses).This NASA-specific information and resource is available in at the System for Administration, Training, and Educational Resources for NASA (SATERN), accessible to NASA-users at https://saterninfo.nasa.gov/.
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
6.1 NASA Lessons Learned
- Pre-Flight Problem/Failure Reporting Procedures. Lesson Number 0733 519: Impact of Non-Practice states: "Without ... formal reporting procedures, problems/failures, particularly minor glitches, may be overlooked or not considered serious enough to investigate or report to Project Management. This could result in recurrence of the problem/failure during the mission and result in significant degradation in performance."
- Problem Reporting and Corrective Action System. Lesson Number 0738 520: Impact of Non-Practice states: "Hardware/software problems that require further investigation may not be identified and tracked. Development of corrective action and need for improvement will not be highlighted to engineering. Opportunities for early elimination of the causes of failures and valuable trending data can be overlooked." Practice states: "A closed-loop Problem (or Failure) Reporting and Corrective Action System ( PRACAS or FRACAS ) is implemented to obtain feedback about the operation of ground support equipment used for the manned spaceflight program."
6.2 Other Lessons Learned
No other Lessons Learned have currently been identified for this requirement.