Reporting bugs
This guide will help you understand how to recognize potential GDS bugs, submit useful reports, and collaborate with our development team for timely resolutions. Remember, your input is invaluable in enhancing the functionality and user experience of GDS.
Is it a GDS bug?
So you’ve found a UI bug in a project which is using GDS and you would like to report it. The first step is to find out to whom to report it. Only some of the UI problems are GDS bugs.
Identify component
Identify whether your bug concerns a GDS component. Take a look at the GDS Storybook, which contains all of our components. If your bug concerns a component that is not in the GDS Storybook, please report it to the frontend team responsible for the feature. Sometimes there are custom frontend components that are similar to GDS components.
If you want to be thorough, you can install Trigger GDS debug info bookmarklet, which highlights the GDS components in frontend for you.
Check documentation
If you have found the problematic component in GDS, please take a look at its documentation. Make sure that your bug is not the described intended behaviour.
Reproduce
Can you reproduce the issue in the GDS Storybook or GDS Documentation? If yes, then the bug belongs to us and you can write the bug report.
You can also try to reproduce the bug in GDS Playroom. The easiest way to do that is to hover over one of the demos in the documentation of a particular component and click Open in Playroom. In Playroom you can change the configuration of the component to your needs. Don’t be intimidated, it is simpler than it looks.
Consult frontend
If you are still unable to reproduce the bug anywhere in GDS, there is a high chance that it is not a GDS bug. Please consult your frontend engineers. They should be able to either help you reproduce it or at least determine whether the bug seems to be a GDS bug quickly.
We are here to talk
If you are dealing with an unusual issue and you are still not sure how to proceed, feel free to reach out and ask the community in #design-system-web Slack channel. We can take a look at the problem together.
Write a report
The best GDS bug report contains the following:
- A Playroom or Storybook link where the bug manifests.
- An explanation of what is wrong and how it should be. If you can include a reference to why it should be different (our documentation, specification, a Slack conversation, etc.), it’s beneficial.
- The browser and OS versions affected. You don’t need to check all of them, but please state at least one. In case of accessibility bugs, please include the used accessibility software.
If you include instructions on how to reproduce the bug in George Web, we can do that. We don’t prefer it though, because we need to isolate the problem to GDS anyway and we don’t yet know whether the bug even belongs to GDS.
Please don’t include business logic in your report, since as a design system library it is meaningless for us.
File in Jira
If you have identified that the bug is indeed a GDS bug and have prepared your report, you are ready to file it in Jira.
Please take a look at our Issue tracking guide.