Bug Reports¶
If you think you have discovered a bug, you can help us by submitting an issue in our public issue tracker, following this guide.
Before Creating an Issue¶
With numerous users, issues are created regularly. The maintainers of this project strive to address bugs promptly. By following this guide, you will know exactly what information we need to help you quickly.
Please do the following before creating an issue:
Upgrade to Latest Version¶
Chances are that the bug you discovered was already fixed in a subsequent version. Before reporting an issue, ensure that you're running the latest version.
Bug fixes are not backported
Please understand that only bugs that occur in the latest version will be addressed. Also, to reduce duplicate efforts, fixes cannot always be backported to earlier versions.
Remove Customizations¶
If you're using customizations like additional configurations, remove them before reporting a bug. We can't offer official support for bugs that might hide in your overrides, so make sure to omit custom settings from your configuration files.
Don't be shy to ask on our discussion board for help if you run into problems.
Search for Solutions¶
At this stage, we know that the problem persists in the latest version and is not caused by any of your customizations. However, the problem might result from a small typo or a syntactical error in a configuration file.
Before creating a bug report, save time for us and yourself by doing some research:
- Search our documentation for relevant sections related to your problem. Ensure everything is configured correctly.
- [Search our issue tracker] as another user might have already reported the same problem.
- [Search our discussion board] to see if other users are facing similar issues and find possible solutions.
Keep track of all search terms and relevant links; you'll need them in the bug report.
If you still haven't found a solution to your problem, create an issue. It's now likely that you've encountered something new. Read the following section to learn how to create a complete and helpful bug report.
Issue Template¶
We have created a new issue template to make the bug reporting process as simple as possible and more efficient for our community and us. It consists of the following parts:
- Title
- Context optional
- Bug Description
- Related Links
- Reproduction
- Steps to Reproduce
- Browser optional
- Checklist
Title¶
A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug can be inferred from the title.
| Example | |
|---|---|
| Clear | apply command fails with specific CRD |
| Wordy | The apply command fails when used with a certain Custom Resource Definition |
| Unclear | Command does not work |
| Useless | Help |
Context optional¶
Before describing the bug, you can provide additional context to help us understand what you were trying to achieve. Explain the circumstances under which the bug happens, and what you think might be relevant. Don't describe the bug here.
Bug Description¶
Provide a clear, focused, specific, and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported, and not to one of its dependencies. Follow these principles:
- Explain the what, not the how – don't explain how to reproduce the bug here, we're getting there. Focus on articulating the problem and its impact.
- Keep it short and concise – if the bug can be precisely explained in one or two sentences, perfect. Don't inflate it.
- One bug at a time – if you encounter several unrelated bugs, create separate issues for them.
Related Links¶
Share links to relevant sections of our documentation and any related issues or discussions. This helps us improve our documentation and understand the problem better.
Reproduction¶
A minimal reproduction is essential for a well-written bug report, as it allows us to recreate the conditions necessary to inspect the bug. Follow the guide to create a reproduction:
[ Create reproduction][Create reproduction]{ .md-button .md-button--primary }
After creating the reproduction, you should have a .zip file, ideally not larger than 1 MB. Drag and drop the .zip file into the issue field, which will automatically upload it to GitHub.
Don't share links to repositories
While linking to a repository is a common practice, we currently don't support this. The reproduction, created using the built-in info plugin, contains all necessary environment information.
Steps to Reproduce¶
List specific steps to follow when running your reproduction to observe the bug. Keep the steps concise and ensure nothing is left out. Use simple language and focus on continuity.
Browser optional¶
If the bug only occurs in specific browsers, let us know which ones are affected. This field is optional, as it is only relevant for bugs that do not involve a crash when previewing or building your site.
Incognito Mode
Verify that the bug is not caused by a browser extension by switching to incognito mode. If the bug disappears, it is likely caused by an extension.
Checklist¶
Before submitting, ensure you have:
- Followed this guide thoroughly
- Provided all necessary information
- Created a minimal reproduction
Thanks for following the guide and creating a high-quality bug report. We will take it from here.