Skip to content

How to Report an Issue

Lance Campbell edited this page May 1, 2013 · 39 revisions

How to deal with issues

 

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.

Existing issues, feature backlog

Please review the existing issues – GitHub provides a search field to search for Issues and Milestones, found in the top right:

![search in github](https://github.com/adobe/brackets/wiki/screenshots/issues_search.jpg)

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.

How to file an issue or feature request

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).

Determine the priority

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)

Use of lables for issues found in Brackets

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
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
Linux 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

Feature requests

For feature requests, please file them in the issue tracker; they'll be converted to user stories on the public Brackets backlog.

Extension Bugs

Sometimes a bug is caused by a Brackets extension. Before you file an issue on the core product you should first rule out all of your installed extensions. Eventually, Brackets will have an automatic way to enable and disable extensions. For now it must be done manually:
  1. Select Brackets > Help > Show Extensions Folder.
  2. Move all of the extensions from the user directory to the disabled directory, then reload or restart Brackets.
  3. If you can still reproduce the issue, file the issue on Brackets.
  4. If you can't reproduce the issue, you can test each extension individually by moving them back to the user directory one at a time. If you find an extension bug, please file an issue for the extension so it can be addressed by the extension author.
  5. Make sure all of your extensions are moved back into the user directory, then reload or restart Brackets.

Retrieving SHA for current commit

You can retrieve the SHA hash for the current commit that you are using by running the following command:

git rev-parse HEAD

What happens to the issues I filed?

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.

Issues we won't 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.

No priority

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

Issues we close

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!

Clone this wiki locally