How to create a bug report
No software is perfect. This is doubly true for a software as flexible as midPoint. We do our best to test thoroughly, but each deployment is different and you may tread territories where no one has gone before. This article describes how to report bugs so that we can address them efficiently and as quickly as possible. For that to be possible, we need you, the reporter, to cooperate and provide all the necessary information for us to identify the issue and address it. For example, reporting that "Provisioning does not work" does not provide enough information and subsequently wastes both our and your time.
Quick bug reporting checklist
-
Do you run a supported version of midPoint?
-
Are you reasonably sure the problem is not in your configuration rather than in midPoint itself?
-
Can you describe the configuration and steps leading to the issue so that anyone can reproduce it with the same result?
-
Did you sanitize all the bug report attachments (screenshots, configuration, logs, …) required for the issue description so that they can be made public on the Internet?
If you answered yes to all the questions, go to the Support portal and submit the bug. Be sure to follow the bug reporting best practices.
For details and other tips on using the Support portal, refer to the rest of this article.
|
DO NOT report security vulnerabilities in the Support portal!
Please follow the security issue reporting guide to report security vulnerabilities responsibly. Do not use the public issue tracking system for that. |
Before you report a bug
First of all, please make sure to go through Usual Troubleshooting Steps to understand the issue you are facing better.
MidPoint is very flexible and a simple misconfiguration may easily look like a bug. We invest a considerable effort into making the error messages and log entries understandable. However, nothing is perfect and what appears to be perfectly understandable to us may look like gibberish to you. In such a case, we would appreciate your feedback.
Firstly, though, go through the midPoint documentation and try to understand how midPoint works. If the message still makes no sense to you, then it is time to log a bug report.
Even if you succeed, find the problem, and resolve it, we would still appreciate your feedback. You might have spent four hours figuring out the solution, but maybe an improvement of a single log message, for example, could have saved that time. We would be more than happy to make the improvement if you let us know.
You can also contribute the improvement yourself. MidPoint is an open source project and we gladly accept contributions.
When you report an issue, it is important that you run a supported version of midPoint. See the MidPoint Releases for the list of supported versions. Subscribers can purchase an extended or vintage support for a version. The support is then based on the individual contractual agreement.
An issue must be reproducible
To fix a problem, we must be able to replicate it. That means we need you to show us how to reproduce the issue on our side. This is to not only fix the problem, but to handle its cause as well. It also gives us the option to configure an automated test case to ensure the issue does not appear again.
The best way is to describe what configuration is required and steps to be taken to reach the issue in a clean official midPoint build. This saves you a lot of time describing your environment and we do not have to make unrelated configurations on our side to match it. It is also a way for you to check you are not about to report a configuration error as a product bug.
|
Never share sensitive information in the Support portal
Please be sure to anonymize all data you provide on the Support portal. This is especially important to keep in mind when attaching log files and screenshots as these may contain your classified or personally identifiable information, such as e-mail addresses. Remember that the work packages you create can be seen by anyone on the Internet. |
What about non-replicable problems?
If the problem cannot be replicated on a simplified setup, then we need to work with what we have. In such a case, we either need to know a lot about your environment to replicate it in our lab, or we need your cooperation and access to your environment to diagnose the issue.
Where to submit bug report
To submit a bug report, suggest an improvement, or request a feature, use our issue tracking system referred to as Support portal. After you submit a report there, you can use it to track the progress of the issue resolution, add additional information, etc.
We use OpenProject for our issue tracking system. OpenProject uses the term work package throughout its UI for what other systems call "issues" or "work items". Whether we talk about "issues" or "work packages", we mean the same thing in the context of the Support portal, our issue tracking system.
If you cannot use the Support portal for whatever reason, use another available channel, e.g., the one agreed upon in your service contract. We strongly recommend using the Support portal, but we do not enforce it and we appreciate feedback regardless of the channel you use.
|
DO NOT report security vulnerabilities in the Support portal!
Please follow the security issue reporting guide to report security vulnerabilities responsibly. Do not use the public issue tracking system for that. |
Bug reporting best practices
To create a useful bug report, provide the following information:
-
What steps you took and what was the goal.
Some issues may be caused by trying to achieve something using a wrong mechanism. Having a broader perspective helps us to help you. -
If there is a form or other input to the operation, provide the setup and the input data (e.g., an XML snippet you tried to import, or information you filled into a GUI form).
-
What kind of resource definition was used, how it was modified, the relevant object types, mappings, etc.
We need to know only the relevant parts. If unsure, it is better to provide more rather than omit something that is in fact relevant. -
Any special settings that you think may influence the outcome (custom schema, unusual mapping expression, etc.).
-
If the operation produced an error message in the GUI, include that error message as well.
-
If there is an exception in the log files, make sure to include full stack trace of the exception. The exception stack trace is usually a very efficient pointer to the likely cause of the problem.
-
Relevant part of the log files. You may want to look at Useful Loggers to correctly set up your logging in order to get the most useful data in the logs.
-
Your environment: operating system, Java version, relevant target system information, etc.
-
Indication of midPoint version (release) or subversion revision (trunk) that was used.
How to fill in the report form
This section describes how to fill in the fields in the work package create form.
|
Never share sensitive information in the Support portal
Please be sure to anonymize all data you provide on the Support portal. This is especially important to keep in mind when attaching log files and screenshots as these may contain your classified or personally identifiable information, such as e-mail addresses. Remember that the work packages you create can be seen by anyone on the Internet. |
-
Work package type: Select bug for bugs and improvement for improvement ideas and feature requests.
-
Subject (title): Summary of the issue.
Avoid generic titles, make it specific and understandable. This is the field people see when they search for issues. Prefer precision and accuracy over brevity but keep it reasonable. -
Description: Details about the issue.
Provide steps required to reproduce the problem. Your issue may be specific to your setup, the description needs to help reproduce the environment in which the issue exhibits. -
Priority: How important is the fix of the issue for you.
This value does not correlate directly with your perception of the issue severity, partly because some levels are reserved for active subscribers.
Refer to Support Guidelines for the explanation of the priority values.
Please do not abuse the priority. It is better to start lower and escalate if required than have us lower the priority upon the issue clarification. -
Affected versions: The versions on which the issue exhibits. You can fill in multiple versions if you replicated the issue in them all.
-
Backport versions: Use when you want the fix to get to a specific older supported version; available only to eligible subscribers. The versions available in the drop-down list are the nearest next patch versions in which the change can be released.
-
Subscription: Subscription indication based on which we prioritize the issue:
-
Active subscription: You have an active subscription, be it directly or via a partner. Work packages submitted by subscribers get higher priority and are subject to SLAs.
-
No subscription (community): You do not have an active subscription, i.e., you do not pay for Evolveum services. Community-reported issues are treated on the best-effort basis.
-
Sponsored feature: Use if you are a subscriber paying for development of a specific feature and the issue is related to the feature.
-
Do not use internal and unknown.
-
If you are a subscriber, do not forget to fill in the Customer ID.
-
-
Customer ID: The identification of the customer. In case you are a partner logging an issue on behalf of your customer, use their customer ID. This is not the subscription ID stored in the System Configuration object—never share that one.
-
Component: The component that is likely responsible for for the issue. Leave blank if you do not know.
-
Git Revision: Specify the Git revision when using an unreleased midPoint version (e.g., builds from one of the supported support branches).
-
Do not fill in the fix versions, assignee, and accountable fields. These are set by the Evolveum team.
-
Environment: Whatever may be relevant regarding the environment in which you have encountered the issue.
-
E.g., midPoint build info, OS/container info, repository type, database version, JVM and cluster info, memory, connected systems info, etc.
-
-
Attachments: Files like screenshots or trace and log files. You can also paste images directly into the description field.
All files you attach are accessible in the Files tab after you save the work package.
Not all of the above is required in a bug report. Use your common sense. As a rule of the thumb, more information is usually better. At the same time, though, too much irrelevant information may obscure a tiny problem that would be obvious if you provided just the right amount of information.