How to Report an Issue
You tested Brackets and found an issue - now you want to file it – that's great!
While you help us to improve the quality of Brackets, please keep a few steps in mind to help us manage issues in Brackets.
Bugs are tracked in the GitHub issue tracker.
Please review the existing issues – GitHub provides a search field to search for Issues and Milestones, found in the top right:
Typing into the serch field will show related issues, this illustrates the importance of choosing keywords within titles, such that others don't file duplicates for your issue. Some of the issues – basically enhancement requests – are moved to our public backlog, please consider to search through the existing user stories too. There you most likely will find the missing features, enhancements to existing features, etc.
If you find an issue which seems to cover your case you may add comments or scenarios which are specific to your workflow or content. You can also vote for backlog items to help us prioritize.
Filing an issue is simple, click on the "New Issue" button, add a title and a description. We want to provide some guidance regarding which information should be contained in the description, how we consider to set priority, and how we make use of labels in GitHub.
Thanks for supporting our project and other contributors - To enhance reproducibility we ask you to provide information necessary to understand and confirm issues.
- Brackets version/sprint number (please use sprint labels or commit SHA if you're pulling directly from the repo (see below)).
- Platform/OS version (please use labels for Windows / Mac)
- Reproducible steps, actual and expected results
- Link to test files (you can create a gist on gist.github.com if that's convenient).
We differentiate three priorities for issues, we use labels on GitHub to set the priority:
- High: crashes/data loss unless they're very unlikely edge cases
- Medium: functional/ui issues that are at least somewhat severe and that a significant number of users will hit
- Low: issues that have low severity and/or low frequency
- No Priority: issues will remain open but the Brackets development team is not planning to fix (see more about No Priority issues below)
| group | labels | usage |
|---|---|---|
| Process | fix in progress | Bug has been assigned and assignee has started to make improvements |
| fixed but not closed | issue has been fixed but not merged, may need to be regressed | |
| last reviewed | maker for last reviewd bug, see below for explanation of the review process | |
| move to backlog | enhancement marker - to be put on the backlog | |
| sprintN | tag for issues to be addressed in sprint N | |
| starter bug | This issue doesn’t require deep knowledge of the architecture and is the recommended level for new contributors | |
| documentation | insufficient documentation | |
| Priority | high priority | crashes/data loss unless they're very unlikely edge cases |
| medium priority | functional/ui or performance issues that are at least somewhat severe and that a significant number of users will hit | |
| low priority | issues that have low severity and/or low frequency, cosmetic issues | |
| no priority | This is a low priority issue we will leave open but do not intent to fix - please refer to the explanation below. | |
| External tracking | codemirror | needs CM code changes |
| webkit | needs code changes within webkit | |
| LESS | needs code changes within LESS module | |
| cef | needs code changes in CEF sources | |
| tracking | issue is being tracked for example due to dependencies not yet resolved | |
| Architecturally-focused | Win only / Mac only | platform specific issue |
| architecture | To fix this issue significant architectural change is required or desired | |
| async | asynchronous processing / runtime issue | |
| code cleanup | provides an opportunity to do code cleanup, basically, it's a tag that means small, opportunistic refactorings that don't require major cross-cutting changes | |
| performance | preceived or measurable performance issue | |
| native shell | needs code changes in the native shell |
For feature requests, please file them in the issue tracker; they'll be converted to user stories on the public Brackets backlog.
You can retrieve the SHA hash for the current commit that you are using by running the following command:
git rev-parse HEAD
We're reviewing the new issues regularily the 'last reviewed' label is being used to indicate the last bug which has been reviewed. During the review we make sure the appropiate lables are used for the bug. If an issue is related to the work of the current sprint we tag it with the current sprint tag. If it feels rather like an enhancement request we will tag it as 'move to backlog'. In addition we identify starter issues 'starter bug' for individuals who want to start to contribute.
Before you fix a bug, post to the brackets-dev Google group or the #brackets IRC channel on freenode about what you're thinking of working on, so you can get early feedback. If you start to contribute code to Brackets please also consider reading some of our wiki documents like How to Hack on Brackets and Coding Conventions.
The Brackets team needs to assign or label bugs, therefore we ask you to document the progress to trigger necessary changes along the bug lifecycle.
Once you start to adress a bug please let us know and add a note to set it to 'fix in progress', this helps to avoid multiplied efforts. Once an issue is fixed a the contributor opens a 'pull request' to inform the core team to get the bug fix reviewed. After potential adjustments according to the review feedback have been added we will 'merge' the bug fix into master. At this point the status of the bug will be set to 'fixed but not closed' and the filer will 'close' the issue (or notify the team) once he verified the fix.
The consensus is that closing some of the low priority issues would only feel appropriate under specific criteria/circumstances, we don't want to end up burying issues which are affecting the quality of Brackets or are otherwise important to the community. We encourage feedback and contributors actually may review and request to re-open issues in case they feel strongly about them.
Items we keep open but will not work on soon.
| No Priority | High risk / low impact |
| High effort / low impact | |
| Underlaying code or architecture is changing / will change soon |
| Category | Description |
|---|---|
| Feature not supported | Feature is 'as designed' and the request is not an enhancement. |
| Feature removed or beyond scope of Brackets | |
| Not this product | Feature or issue is not in our product and we have no reasonable way to influence the fix being made |
| Intermittent or not reproducible | basically a flavor of high effort / low impact ( at times we may need additional information to reproduce a bug, those cases don't fall into this category if we're able to gather the information necessary with reasonable effort ) |
Thanks a ton for your support and contributions to Brackets!