In accordance with NASA-GB-8719.13, NASA Software Safety Guidebook , problem reports describe "unexpected behavior of the software or system, the analysis performed to determine the cause, and what was done to correct the problem. Projects usually have a formal system for problem reports after the software has reached a level of maturity. However, defects or problems that occur before this time are also important. Tracking these problems, or at least reviewing them to make sure no major defect slips through, is recommended in safety-critical systems."
In accordance with NASA-STD-8719.13, Software Safety Standard, "Discrepancy reports 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. Requirement SWE-113 (shown above) of NPR 7150.2, NASA Software Engineering Requirements, provides a longer list of required content for change requests and problem reports. This required 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.
Typically, change requests are initiated by the person finding the problem, such as the customer, developer, or tester. These reports are reviewed for safety implications; therefore, the content needs to be as clear and as complete as possible.
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 required 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, Field Programmable Gate Array (FPGA) 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.
Consult Center Process Asset Libraries (PALs) for Center-specific guidance and resources related to the content of change requests/problem reports.
Additional guidance related to the content of change requests/problem reports may be found in the following related requirements in this Handbook: