How To Handle a Product Issue
A product issue is a uniquely identified problem impacting a product, requiring clear communication with various stakeholders. It must be documented with accurate information and version details and managed in parallel with bug management and product releases.
This guide describes the workflow to create and maintain product issue information and the need to get it approved before it is published. It also includes - under Details - further information about product issues, related processes, responsible roles, and product issue metrics.
Intended for
Product owners, release owners, software and hardware engineers, product managers, L4 engineers, L4 coordinators, L3, and anyone within PCP R&D who is responsible for bug management.
Activities
The handling of product issues can be summarized in four key activities:
Identify a PIN
When a product issue has been identified - whether through a support case or an internal bug considered severe enough to require field communication or inclusion in release notes - a unique identity of the product issue must be created; a product issue number (PIN). The PIN must be based on the common syntax described in Product Issue Number.
The unique PIN is used as a reference in all related support cases and bugs, and for communication with stakeholders outside PAPCP.
When the PIN is generated, the following basic information needs to be available, and can be collected from a related bug:
- A draft description of the issue.
- The product the issue is found in.
- A preliminary product release in which the issue was introduced.
An existing PIN may also be identified to require maintenance, as described in Prepare a product issue.
The product owner is accountable for having a PIN generated for a product issue and for maintaining the information stored in the Product Issue Database (PID).
Prepare a product issue
A product issue must provide information about the following:
- "Description": A description of the issue, from an end-user perspective.
- "Clarification/Workarounds": Any details to clarify the issue and available workarounds.
- "Correction/Fixed": A short common statement that the issue has been corrected, e.g. “The problem has been corrected”, and any details that may be needed to describe how the change affects the functionality.
- "Introduced In": One or several product releases in which the issue was introduced.
- "Resolved In": None or several product releases in which the issue has been corrected.
A product issue must be updated with valid information whenever any of the events listed in the table below occurs. The table also lists who is responsible for updating the product issue for each event.
| Event | Type of information | Responsible |
|---|---|---|
| A related bug has been updated with new details on how, when, and in which product version the issue may occur. | Description Clarification/Workarounds Introduced In | SW/HW Engineer |
| A correction has been applied in a product version. | Correction/Fixed Resolved In | SW/HW Engineer |
| A bug clone is created for a new targeted product version. | Resolved In | Release owner |
| A field communication is published. | Document Id Type of field communication | Product owner |
The product owner is accountable for having the product issue prepared with proper information.
Approve a product issue
A product issue must be approved before it can be officially published.
For a product issue to be approved it must:
- Include a description of when and how the issue may occur, described from an end-user perspective.
- Refer to at least one product release it was introduced in.
- Have been reviewed by at least the product owner, release owner, L4 coordinator, or product manager.
The product owner is accountable for having a product issue approved.
Publish a product issue
A product issue can be officially published whenever in time, as long as it has been approved.
The table below lists some use cases, and responsible roles, when a product issue may be suitable to publish.
| Event | Responsible |
|---|---|
| A related product release, where the issue is known or resolved, is published. | Release owner |
| A field communication is published. | Product owner |
| The issue is to be communicated before any new product release or field communication is published. | Product owner |
Examples of publication forms:
- PID (master)
- Release notes
- Field communication
The product owner is accountable for publishing a product issue.
Details
About product issues
It must be possible to follow up on which versions of an affected product a product issue applies to and/or has been resolved. A product issue must also provide a good description of the issue from an end-user perspective and other types of detailed information.
A product issue may be related to one or several bugs, support cases, and field communications.
From a bug perspective, several bugs may refer to the same product issue, using the PIN, since a bug is version-dependent. A bug often contains more technical details of an issue, which code or hardware is failing, and what suggested solutions exist, which may differ depending on the version of the product it refers to.
From a support case perspective, several cases may refer to the same product issue since the issue can be found by different customers on different sites and systems.
A field communication may refer to one or several different product issues, all depending on the context of the communication.
All product issues are stored and maintained in a common database - the PID - which supports the process.
Related processes
The product issue process is closely related to the following processes as visualized below:
- Bug management (see How-to Manage Bugs)
- Release management
- L4 & Maintenance
Roles and Responsibilities
The workflow of handling product issues includes four key activities/tasks with the following responsibilities:
| Task | Product Owner | Release Owner | Product Manager | SW/HW Engineer | L4 Coordinator | Comments |
|---|---|---|---|---|---|---|
| Identify a PIN | A/R | I | [I] | - | I | - |
| Prepare a product issue | A/R | R | - | R | - | - |
| Approve a product issue | A/R | C | C | I | C | - |
| Publish a product issue | A/R | R | I | - | I | - |
Metrics
The PIN process will establish the possibility to collect the following KPIs:
- Corrected PINs per release.
- Introduced PINs per release.
- Time from creation to first publication, rejection, or still in a "New" state.
- Approved PINs that never were published.