Are you frustrated because your bug reports don’t get fixed or are misunderstood? Learn how you can get things fixed quicker by framing software issues in an understandable and actionable way.
GitHub Support receives a variety of reports ranging in type, frequency, and quality every day. We’re sharing how we approach the reports we receive in the hopes that it will help you write your next report for GitHub.com (and you could possibly apply some of these strategies for reporting a bug on project you’re working on, too!).
What’s a bug report?
A bug report is a write-up that describes a situation where existing behavior contradicts expected (but not always documented) behavior.
Bug reports are different from feature requests. Feature requests focus on introducing a new feature that has yet to exist or expanding an existing feature’s scope with more functionality.
How do I submit one?
It depends on the report! 
- If your report involves any sensitive data, the best place to report that is through our Contact Form.
- If you’ve found a security vulnerability, our GitHub Security team would
to hear from you. Check out our GitHub Security Bug Bounty for more details. - For anything else on GitHub.com, open a new topic in the relevant category that describes your experience of existing behavior contradicting expected (but not always documented) behavior.
Once opened, a member of the GitHub Support Team will follow up with additional questions or an evaluation of your report.
How does GitHub Support handle and write bug reports?
When GitHub Support receives a bug report, we have two goals: understanding and evaluation. The whole process can be summarized in the following acrostic, BIDE:
- Behavior
- Instruction
- Demonstration
- Evaluation
One could say that we BIDE our time to understand what’s being reported before reaching any conclusions.
Understanding
To develop a clear understanding of the problem, we ask ourselves the following questions about behavior, instruction, and demonstration.
If your bug report doesn’t include enough information for us to answer every question, we may need to follow up with you before making an evaluation. Answering these questions in your bug report is the best way to help one of our support engineers get up to speed!
Behavior
- What are the expected and actual behaviors? How are they different?
- Is there documentation for the expected behavior?
Instruction
- Are there instructions for reproducing the problem?
- When (date & time) and where (exact URL) did the problem occur?
- Was the user logged in or authenticated?
Demonstration
- For GitHub.com
- are there screenshots or a motion picture (GIF) demonstrating what happened?
- are there any textual logs showcasing server errors from the browser’s console?
- For the GitHub API: are there any
curl -voutputs that demonstrate the issue at hand?
Evaluation
The last part of the process is evaluation: is the reported behavior expected or a bug?
If the behavior is expected, we provide an explanation and accompanying documentation if available. If you have thoughts about how the behavior could be improved, our team would love to hear them! Our product team tracks the requests through our official product feedback form.
If the behavior is unexpected, we’ll acknowledge it and open an internal issue to inform the responsible team. If there are any workarounds or alternatives, we’ll do our best to tell you. We can’t make any promises or offer a timelines for any fixes, but we are always open to answering any follow-up questions in the meantime.
The Anatomy of an internal bug report
We’re sharing how we write bug reports to offer you another perspective for framing future issues. If your bug report is confirmed by our team, we open a new GitHub Issue in the appropriate repository.
The issue title serves as a “first impression” to the reader.
The issue body includes the following items:
-
@mentionto the responsible team(s) - a link to the original report for context
- a summary of the expected and actual behaviors
- steps for reliably reproducing the actual behavior
- an accompanying demonstration (usually in the form of screenshots or a GIF)
Once the issue is created, the responsible team triages it and offers input, be it a fix in the form of a pull request, a workaround in lieu of an immediate fix, or additional questions to gain a better understanding of the issue at hand.
Example of putting it all together
Here’s an example of the entire bug discovery and report process.
Imagine I log in and navigate to my profile page at https://github.com/francisfuzz. When I attempt to load that page, the page loads a unicorn and a message that the page is taking too long to load. If I log out and navigate to my profile page, I don’t see the unicorn anymore.
I navigate to the How to Use Git and GitHub category, press 
New Topic, and populate the title with the following text:
Navigating to my user profile returns a Unicorn (page is timing out)
Under “How can we help?”, I describe my experience:
Hi GitHub Support!
When I navigate to my user profile, the page loads a unicorn and let’s me know that it’s taking way too long to load:
https://github.com/francisfuzz
This is unexpected behavior because I expect to see my profile as it’s documented here: https://help.github.com/articles/about-your-profile/
Also, I noticed that I only see the unicorn when I’m logged in. If I’m logged out, I don’t see the unicorn anymore.
Here’s a screenshot of what I’m seeing:
Could you let me know if you have any workarounds to this? Thanks for all your help!
With this information, a GitHub Support Team member can try to reproduce the issue themselves and pass on the bug report to the appropriate team.
What do you think?
How do you write your bug reports? We’d love to hear your thoughts. Maybe we can improve the way we do things!
I’ve updated the copy with the latest guidance. Thanks for your patience everyone!