-
Notifications
You must be signed in to change notification settings - Fork 7.6k
How to Report an Issue
Whether you've found an issue with Brackets, the Brackets Registry or the Brackets Shell, you should file your issues according to these instructions.
Found a bug you'd like to tell us about? Here's what to do...
First, check our Troubleshooting page for solutions to common problems.
Brackets bugs are tracked in the issue list on GitHub. Always search for existing issues before filing a new one (use the search field at the top of the page).
When filing a new bug, please include:
- Descriptive title - use keywords so others can find your bug (avoiding duplicates)
- Specific, repeatable steps to trigger the problem
-
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) - OS version
- List of installed extensions (or mention if you've tested with Debug > Reload Without Extensions)
- Any errors logged in the Debug > Show Developer Tools Console view
Bugs can be caused by Brackets extensions you've added. Before you file an issue on Brackets core, use Debug > Reload Without Extensions to see if the problem still occurs without any extensions. See "Extension bugs" below for details.
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 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.
Bugs can be caused by Brackets extensions you've installed. Before you file an issue on Brackets core, use Debug > Reload Without Extensions to see if the problem still occurs without any extensions. If you can still reproduce the problem, file an issue on Brackets.
If you can't reproduce the problem, then the issue lies with one of your extensions. See Troubleshooting extension bugs for tips on identifying which extension is causing the problem.
Once you know which extension causes the bug, please file an issue in that extension's repo so it can be addressed by the extension author.
We review all new issues on a regular basis (the issue tagged 'last reviewed' is the most recent one reviewed). Several things typically happen as part of review:
- Is the issue clearly understandable? If not, we'll ask for clarification (tagging the filer with "@").
- Is the issue more of a feature request? If so, we'll tag it 'move to backlog'; these items are periodically migrated to our feature backlog.
- Labels are added to indicate priority - high, medium, low, or none (read more below). Bugs may also be assigned a sprint milestone - if they are urgent or related to features under development in the current sprint.
- Labels may be added to categorize the bug. See "Understanding issue labels" below.
- Would the fix be a good intro to the Brackets source code? If so we'll tag it 'starter bug' to encourage Brackets newcomers to work on it.
- Most bugs are assigned to a Brackets core committer right away. Depending on priority, milestone, and other workload, the 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.
The process above covers the first two steps. Here are the rest:
- New bug is filed; awaiting review -- bug is newer than 'last reviewed' tag
- Triaged in bug review -- bug is assigned to a developer
- Developer begins working on it -- bug is tagged 'fix in progress'
- Developer opens a 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 original filer is requested 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 sprint the fix landed
Yes please! But first...
- Check to make sure no one else is already working on it. If the bug has a sprint milestone assigned or is tagged 'fix in progress' then it's already under way. Otherwise, post to the brackets-dev newsgroup, the #brackets IRC channel on freenode, or the bug comment thread itself (pinging the assigned developer via "@") to check.
- Read the guidelines for contributing code - especially, make sure you're following our [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 try to have zero high-priority bugs before shipping each sprint. |
| medium priority | Bug that's at least somewhat severe and a significant number of users will hit. We closely track the number of medium-priority bugs. | |
| low priority | Low severity (e.g. small cosmetic issue) and/or few users will hit. May not be fixed for a while. | |
| no priority | Impact is so low that we don't plan to ever spend time fixing the bug - but we would accept a fix if someone offers a pull request. May be an issue we anticipate will become obsolete due to upcoming UI or feature changes. | |
| Suggestions | starter bug | Fixing this bug would be a good intro to the Brackets source code. Recommended for new contributors. |
| Extension Idea | Feature/enhancement request that's a great idea for a Brackets extension. May be out of scope for Brackets core. | |
| documentation | Fix involves improving documentation rather than writing code. | |
| External tracking | codemirror | Needs CodeMirror changes. |
| cef webkit |
Needs code changes in Chromium Embedded Framework (which brackets-shell is built on) or in WebKit/Chromium itself. | |
| tracking | Specific bug has been filed in external project - waiting on a fix. | |
| Architecturally-focused | architecture | Requires significant architectural changes - to be discussed in meeting or newsgroup. |
| performance | Perceived or measurable performance issue. | |
| code cleanup | Fix involves cleaning up code, improving maintainability without making major architectural changes. (May be the main benefit of fixing the bug). | |
| 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 the bug-process label above.
- 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, browser runtime, etc. Suggests the bug should be closed or tagged "no priority."
Yeah, what's up with that? There are a number of reasons an issue might get closed without being fixed:
- Tagged "move to backlog" - the issue is a larger feature/enhancement request. It's not forgotten! Look for a link in the comment thread to a user story on 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 sprint milestone assigned to the bug). If you're still seeing it, let us know.
- Duplicate - there's already a bug for this (may be part of a larger issue).
- 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 - 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.
- Tagged "no priority" (usually left open) - impact is so low that we don't plan to spend time fixing the bug. But we would accept a fix if someone else is willing to work on it.
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.
Thanks a ton for your support and contributions to Brackets!