Skip to content

How to Report an Issue

ScanuNicco edited this page Sep 25, 2021 · 39 revisions

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.

How to file a bug

  1. Go to our issue tracker on GitHub
  2. Search for existing issues using the search field at the top of the page
  3. File a new issue including the info listed below
  4. 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

If you've installed extensions

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.

Requesting a feature

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.

What happens after a bug is filed?

Bug lifecycle

  1. New bug is filed; awaiting review
  2. Triaged in bug review -- see below ('last reviewed' tag
  3. Developer begins working on it -- bug is tagged 'fix in progress'
  4. Developer opens pull request with a fix, which must be reviewed -- a link to the pull request appears in the bug's activity stream
  5. 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")
  6. Filer agrees that it's fixed -- bug is closed, and its milestone is set to the release the fix landed in

Bug review

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.

Hey! My bug wasn't fixed!

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.

Can I help fix a bug?

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

Understanding issue labels

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

Other bug-related terminology

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.
Clone this wiki locally