How to Report an Issue
Whether you've found an issue with Brackets, the Brackets Registry or the Brackets Shell, here's how to report the problem...
First, check our Troubleshooting page for solutions to common problems.
- Go to our issue tracker on GitHub
- Search for existing issues using the search field at the top of the page
- File a new issue including the info listed below
- Thanks a ton for helping make Brackets higher quality!
When filing a new bug, please include:
- Descriptive title - use keywords so others can find your bug (avoiding duplicates)
- Steps to trigger the problem that are specific, and repeatable
-
What happens when you follow the steps, and what you expected to happen instead.
Include the exact text of any error messages if applicable (or upload screenshots). -
Brackets version (or if you're pulling directly from Git, your current commit SHA - use
git rev-parse HEAD) - Did this work in a previous version? If so, also provide the version that it worked in.
- OS version
- Extensions? Confirm that you've tested with Debug > Reload Without Extensions first (see below).
- Any errors logged in Debug > Show Developer Tools - Console view
Bugs can be caused by Brackets extensions you've added. Before you file an issue, use Debug > Reload Without Extensions to see if the problem still occurs without any extensions.
If that fixes the problem, then please file an issue in the extension's repo instead, so it can be addressed by the extension author. See Troubleshooting extension bugs for tips on identifying which extension is causing the problem.
Please first check our feature backlog on Trello to see if it's already there. You can vote on features in the backlog to help us prioritize them.
Feel free to file new feature requests as an issue on GitHub, just like a bug. We tag these issues "move to backlog" and periodically migrate them onto the feature backlog for you.
- New bug is filed; awaiting review
- Triaged in bug review -- see below ('last reviewed' tag
- Developer begins working on it -- bug is tagged 'fix in progress'
- Developer opens pull request with a fix, which must be reviewed -- a link to the pull request appears in the bug's activity stream
- Pull request is merged, and the bug's filer is pinged to verify that it's fixed -- bug is tagged 'fixed but not closed' ("FBNC")
- Filer agrees that it's fixed -- bug is closed, and its milestone is set to the release the fix landed in
We review all new issues on a regular basis. Several things typically happen as part of review:
- Ping the filer for clarification if needed.
- If the issue is a feature request, we'll tag it 'move to backlog'; the issue will be migrated to our feature backlog at a later date.
- Add priority labels (high, medium, low, or none - read more below).
- Add release milestone - typically only if a bug is a "release blocker" or related to features still in progress.
- Add feature area label, and possibly other category labels like 'starter bug' or 'Mac only.' See "Understanding issue labels" below.
Depending on priority, milestone, and other workload, a developer may or may not begin working on the bug soon.
Some bugs may be closed without fixing - see "Hey! My bug wasn't fixed!" below.
Yeah, what's up with that? There are a number of reasons an issue might get closed without being fixed:
- Tagged 'move to backlog' - It's not forgotten! Look for a link in the comment thread to our feature backlog. Please vote on the story to help us prioritize it!
- Tagged 'fixed but not closed' - We think it's fixed. Make sure you have a Brackets build containing the fix (check the milestone assigned to the bug). If you're still seeing it, let us know.
- Duplicate - There's already a bug for this.
- Unable to reproduce - We're unable to reproduce the result described in the bug report. If you're still seeing it, please reply with more detailed steps to trigger the bug.
- Out of scope / extension idea - This change probably doesn't belong in Brackets core... but it could still make for a great extension!
- Not a bug / fact of life - This is the intended behavior. If it feels wrong, we should discuss how to improve the usability of the feature.
If you disagree with a bug being closed, feel free to post a comment asking for clarification or re-evaluation. The more new/updated info you can provide, the better.
Yes please! But first...
- Make sure no one else is already working on it -- if the bug has a milestone assigned or is tagged 'fix in progress', then it's already under way. Otherwise, post a comment on the bug to let others know you're starting to work on it.
- Read the guidelines for contributing code, [pull request guidelines](Pull Request Checklist), and [coding conventions](Brackets Coding Conventions).
We use labels/tags for a number of purposes:
| label | meaning | |
|---|---|---|
| Process | fix in progress | Someone has started work on a fix (or the fix is ready but still undergoing code review - not merged yet). |
| fixed but not closed | Fix has been merged. Waiting for the original bug reporter to verify that it's fixed. | |
| last reviewed | Last reviewed/triaged bug. See "Bug review" above. | |
| move to backlog | Feature/enhancement request rather than a bug. Will be moved to the feature backlog. | |
| Priority | high priority | High impact bug many users will hit (e.g. crash/data loss). We aim for zero high-priority bugs before each release. |
| medium priority | At least somewhat severe and a significant number of users will hit. | |
| low priority | Low severity (e.g. small cosmetic issue) and/or few users will hit. | |
| no priority | We don't plan to spend time fixing the bug - but we would accept a fix if someone offers a pull request. | |
| Feature area | F ... | Labels starting with "F" categorize bugs by feature area. |
| Suggestions | starter bug | Recommended for new contributors as a good intro to the Brackets source code. |
| Extension Idea | May be out of scope for Brackets core, but is a great idea for a Brackets extension. | |
| External tracking | codemirror | Needs CodeMirror changes. |
| cef webkit |
Needs Chromium Embedded Framework or WebKit/Chromium changes. | |
| tracking | Specific bug has been filed in external project - waiting on a fix. | |
| Architecturally-focused | architecture | Requires significant architectural changes - needs longer discussion. |
| performance | Perceived or measurable performance issue. | |
| code cleanup | The fix improves code maintainability without changing Brackets's functionality. | |
| async | Bug caused by asynchronous execution / race condition | |
| native shell | Needs code changes in brackets-shell, our desktop native wrapper |
Acronyms we use frequently in bug comments:
- FBNC = "fixed but not closed": See bug lifecycle
- UTR = "unable to reproduce": Someone tried to follow the steps in the bug, but everything seemed to work fine.
- NAB = "not a bug": The behavior described in the bug is actually how it's supposed to work. This may indicate a usability or documentation problem.
- FOL = "fact of life": The bug is virtually impossible to fix due to constraints of the OS, runtime, etc.