Skip to content

Bug reports

Reproducing a problem under the same conditions helps us investigate it and find a solution faster. This guide explains what to include in your bug report.

Before creating an issue

Please follow these steps before opening an issue:

  1. Upgrade to the latest version. Our software follows an evergreen release model, with bug fixes delivered in the latest release. Update the project and check whether the issue persists.

  2. Search the project's documentation. Check sections related to the problem and make sure that everything is configured correctly. A small typo or incorrect setting might be the cause.

  3. Search the project's issue tracker. An existing issue may already include a workaround or fix you can use immediately, saving everyone time.

  4. Simplify the setup. Remove unrelated settings and components one-by-one while keeping the unexpected behavior reproducible. This narrows down the possible causes.

If the behavior still occurs and no existing issue describes it, create a new one. The next section explains what to include. If the issue might be a security vulnerability, report it privately.

Don't know where to start? Ask the community in our free Discord channel or, if you're a Spark member, in a public Spark space. If the information you need to share may be confidential, use your organization's dedicated private space, if available.

Issue template

Our Open Source projects use issue templates to make bug reports consistent and efficient for reporters and maintainers. They contain the following parts:

Title

Write a short, specific summary of what went wrong and when. Examples:

  • Preview stops updating after an included file is renamed
  • Search omits headings that contain accented characters
  • Build fails when a navigation entry contains an external URL

Context optional

Explain what you were trying to achieve and include any relevant details about your setup. Do not describe what went wrong here; use the Bug description field below.

Why we ask: some errors only appear in specific settings, environments, or edge cases, such as documentation projects with thousands of documents.

Bug description

Explain what happened, what you expected, and how it affected your work. Keep the steps for Steps to reproduce, and create separate issues for unrelated problems.

Workaround: if you found one, include it so others can keep working while we investigate. It may also help us narrow down the cause.

Why we ask: a clear comparison of observed and expected behavior helps us understand the problem, while its impact helps us prioritize the issue.

Reproduction

Every bug report needs a reproducible case. Follow the format requested in the project's issue form, which may ask for a minimal project, input, command, test case, or trace that demonstrates the behavior. Screenshots or videos support the report, but do not replace a reproducible case.

If you cannot share a reproduction publicly, ask in our Discord channel without sharing confidential details, or use your organization's private Spark space if available. If the problem might be a security vulnerability, follow our security reporting guidance instead.

Why we ask: a minimal reproduction lets us inspect the behavior under the same conditions without reconstructing your project or requesting additional details.

Steps to reproduce

List each command or action needed to trigger the behavior, in order. Include any relevant conditions and write for someone unfamiliar with your project.

Why we ask: the reproduction gives us the starting point; these steps show us how to reach the same behavior and confirm that we are investigating the right problem.

Environment

Environment details depend on the project. Follow the issue form and provide exact versions for the systems, tools, or components it asks about.

Why we ask: some bugs occur only with a specific version or environment, so we may need to match your setup to observe the same behavior.

Share links to relevant documentation and related issues you found while looking for a solution. If you found none, write None found.

Why we ask: these links add context and show what you already tried, helping us investigate without asking you to repeat what you already checked.

Checklist

Use the checklist for a final review before submitting your report. Confirm only completed steps and provide any missing information so we can begin investigating.