Guideline#

This document describes the general guidances for Problem Resolution based on the concept which is defined Concept Description.

General Hints#

The detailed implementation of the Problem Resolution for the project shall be described in the Workflow Platform Management.

Templates#

To create problem reports, the project shall provide the content of the following template in project’s selected Issue Tracking System: Problem Template.

Note

An example template for the Issue Tracking System in GitHub (GitHub Issues) can be found here: Issue Template Bugfix

Attributes#

For all Problems following mandatory attributes need to be defined:

Overview of mandatory problem resolution attributes#

Title

Problem attribute: affected versions

Problem attribute: analysis results

Problem attribute: classification

Problem attribute: description

Problem attribute: milestone

Problem attribute:: safety affected

Problem attribute:: security affected

Problem attribute: stakeholder

Problem attribute: status

Problem attribute: title

Problem attribute: UID

A more detailed description can be found here: Process Requirements

Activities for Problem Resolution#

This section describes in detail which steps need to be performed for a Problem Resolution.

Table 17 Activities for Problem Resolution#

Step

Description

Responsible

Approver

1.

Create Problem Report

Contributor

Committer

2.

Analyze Problem Report

Contributor

Committer

3.

Initiate and Monitor Problem Resolution

Contributor

Committer

4.

Close Problem Resolution

Committer

Project Lead

Create Problem Report#

Contributor (as author, submitter, reporter) creates the Problem Report in the defined Issue Tracking System of the project based on the content of the provided template: Problem Template.

It is expected that the select Issue Tracking system supports template definition. Best practice is to define a template with the required content, so that it can be copied from the different users.

Note

For the Issue Tracking System in GitHub, there is a template created, which can be be found here: Issue Template Bugfix

Note

A Problem Report Example based on that template is here: Example Problem Report

Note

A Problem Report Example 2 based on an older version template is here: Example Problem Report 2

It is expected, that the UID will be provided automatically by the Issue Tracking System.

It is expected, that the status of the problem report is set to “open” automatically. As long as the content is updated, the status of the Problem is kept “open”.

It is expected, that the problem submitter will be set automatically by the Issue Tracking System.

The title of the Problem Report should reflect the topic accordingly.

The description should reflect the problem root cause, if known, and its impact, including known side effects on other functionality or dependent components.

Assess notification needs according to Notification of Affected Parties.

Further supporting information should ge given, especially how to reproduce the problem, and what is the error occurrence rate?

If the problem affects safety or security it should be stated explicitly. If safety is affected, the ASIL classification should be added, if applicable.

The problem should be classified according minor, major, critical or blocker.

Document the version where the problem was detected and the first and last affected versions, including versions derived from the faulty version. Where applicable, identify affected branches and dependent integrations. Record unknown affected versions as “under investigation” and update them during analysis.

Note

For the Problem Report Example:
* The UID is provided by the Issue Tracking System as: #631
* The status of the issue is provided by the Issue Tracking System as: Open
* The submitter is provided by the Issue Tracking System as: masc2023
* The title contains the main root cause, missing safety/security attribute
* The descriptions has a section for the Root cause and Impact
* The description has a section for notification: Notification required?
* Further supporting information is added as the link to the official feature request template which makes it reproducible
* Checkboxes are selected to highlight, that Safety and Security is affected, no further classification, as the project is defined as ASIL B
* The problem classification is provided as minor
* The first affected version is provided: pre-0.5
* The last affected version is provided: 0.5

When ready to review and to analyze, the author sets the status to “in review” manually.

Note

For the Problem Report Example:
* The “Process Development Community” dashboard is added and the status must be changed to Todo
* The combination of the issue**Open** and Todo defines the status in review

Notification of Affected Parties#

Notification is needed when the problem’s impact requires affected parties to assess their use of the software or take action, such as applying a workaround or an update. Consider affected users, integrators and feature or component maintainers, and the Safety or Security Manager where applicable.

The Project Lead communicates the problem status to affected parties. Record whether notification is needed and why in the Problem Report’s notification section. If needed, notify the affected parties through an issue comment with an explicit mention or another appropriate channel. Record who was notified, when and how, using a comment link or communication reference. For suspected vulnerabilities, follow the project’s confidential reporting policy.

Analyze Problem Report#

The projects Committer analyzes the problem together with the Contributor and takes a decision for accepting or rejecting it.

The analysis will start by reviewing all the information given during the creation of the problem report. All topics are revisited and checked for correctness, completeness and consistency.

If required, the information is updated accordingly.

If accepted, the stakeholder of the problem and the expected release, where the problem should be closed, shall be defined. Optionally, the corresponding milestone can be set.

If applicable, the features affected should be identified too.

The description shall reflect the result of the analysis.

Where safety or security may be affected, the responsible Safety Manager or Security Manager, respectively, confirms or disconfirms the relevance and records the reason.

A review topic is a question used to check the information and decisions in a Problem Report. A critical review topic must be addressed before approving the analysis. This is independent of the problem severity classification critical. The following topics shall be checked:

  • Critical: Is the problem description clear, including its impact?

  • Critical: Is the root cause described, or identified as under investigation?

  • Critical: Are the occurrence rate and reproduction information provided, as far as known?

  • Critical: Is the problem classification correct?

  • Critical: Are the affected versions identified, including versions derived from the faulty version?

  • Critical: Is the safety or security relevance assessed, where applicable?

  • Is notification needed, and have affected parties been notified?

  • Are proposed solutions, supporting information and related issues or pull requests provided?

  • Are the responsible stakeholders and expected closure version identified?

Disposition of Review Topics#

If a critical topic is not clarified, keep the report “in review” or return it to “open” for further information according to Analyze Problem Report. Record the open question and the analysis result. Missing information alone is not a reason for rejection. If the problem is rejected, document the reason. Rejection or cancellation does not mean that a problem where safety is affected is managed to closure; see Closure of Problems Where Safety Is Affected.

Note

For the Problem Report Example:
* The descriptions has a section for the analysis results: Accepted
* The stakeholder are provided using Assignees field: masc2023
* The expected fix version is provided: 0.6
* The “Milestone” is provided: Release v0.6 - Maturity Level 2
* Feature identification is not applicable for this example, so no label is set, beside bug

If accepted, Contributor can start with the initiation of the Problem Resolution.

The author has the freedom to cancel it at any time by setting the status to “rejected”.

Note

For the Problem Report Example:
* For rejection the status of the issue must be changed to Closed as not planned
* The combination of Closed as not planned and any “Process Development Community” status defines the status rejected

Initiate and Monitor Problem Resolution#

If accepted, the projects Committer initiates the resolution of the problem together with the Contributor.

The description shall reflect the proposed solutions, e.g. measure to resolve the problem.

Note

For the Problem Report Example:
* The descriptions has a section for the proposed Solution

The concrete implementation of the solution may require several additional activities. In this case additional issues may created and linked to the Problem Report.

Note

For the Problem Report Example:
* The Create sub-issue should be used to create further linked issues.

Minimal a Pull Request is sufficient to resolve the problem, which shall be linked to the Problem Report. It is expected, that the status of the Pull Request is set to “draft” or “open” automatically.

When ready to implement, the author sets the status to “in implementation” manually.

Note

For the Problem Report Example:
* The “Process Development Community” status must be changed to In Progress
* The linked Pull Request status is either “Draft” or “Open”
* The combination of Open and any “Process Development Community” status In Progress and the Pull Request status Draft or Open defines the status in implementation

Note

For the Problem Report Example:
* The Development section should be used to link to an pull request
* The Create a branch action may used to create automatically a linked pull request
For the Problem Report Example 2:
* The Create a branch action was used to create a automatically linked Pull Request
* The automatically created branch name reflects the issue UID and the title as
* 126-bug-stkh_req__archdes_example_req-has-no-content

During the resolution the responsible lead Project Lead reports regularly the status to the affected projects teams.

Escalations topics should be documented in the description, if possible.

Note

For the Problem Report Example and Example 2:
* Their is no escalation topic documented

The author has the freedom to cancel it at any time by setting the status to “rejected”.

Close Problem Resolution#

During the resolution the Contributor monitors all activities linked to the problem, until they are closed.

Committer checks finally if the problem Resolution is sufficient before the status is finally closed. To check, if it is sufficient, Problem Checklist may used. Where measures are implemented, confirm their effectiveness and record the verification results. Consider and document side effects of the implemented measure, such as reduced performance, and include them in the verification as applicable. For problems where safety is affected, apply Closure of Problems Where Safety Is Affected.

Closure follows Close Problem Resolution and Problem Report issues closi....

Note

For the Problem Report Example 2:
* The status of the issue is provided by the Issue Tracking System as: Closed
* The combination of Closed and any “Process Development Community” status Done and the Pull Request status Merged defines the status closed

If the resolution is insufficient, keep the status “in implementation”.

Closure of Problems Where Safety Is Affected#

For a Problem Report classified as Safety affected, closure shall be supported by one of the following:

  • An adequate safety measure has been implemented to resolve the problem, based on a rationale, and its effectiveness has been verified.

  • An evaluation concludes that the problem does not constitute an unreasonable risk, supported by a rationale.

For either condition, document the rationale and its review result in the Problem Report. Include effectiveness-verification results for an implemented measure, or the risk evaluation for the second condition. A software fix or fixed version is not required for the second condition.

Without a documented and reviewed rationale, the problem is not managed to closure. These conditions do not change the responsibilities defined in Close Problem Resolution.