- Issue Titles
- Issue Descriptions
- Claiming Issues
- Labels
- Available Issues
- Triaging
- Issue Organization
- Community Friendly
Components
Issues are organized in terms of components. Issue titles should include the name of the component as a tag at the very beginning. Consider the following titles:
- Bad:
Fix input field padding of search bar - Good:
[SearchBar] Fix input field padding
or
- Bad:
Add information about titles to documentation - Good:
[Docs] Add information about titles
Some common tags include:
| Editor | SecondaryPanes | UI | Other |
|---|---|---|---|
| Editor | CommandBar | SourceTree | Accessibility |
| SourceTabs | WatchExpressions | TextSearch | Theme |
| SearchBar | Breakpoints | WelcomeBox | Reducer |
| SourceFooter | CallStack | Action | |
| Scopes | Docs |
User Perspective
The best issue titles are framed in terms of the impact on the user. i.e.
[Editor] search skips odd matches[WatchExpressions] can't remove an expression after it's been edited
Things to try and avoid in the title
- implementation details where possible. Refactoring is an exception where it's okay
- vague language like e.g "debugger crashes", "can't install"
- inflammatory language "Search is terrible". Negative language has two effects, it can make someone feel guilty for breaking something. It can guilt trip someone into feeling like they have to fix it now.
Steps to Reproduce STR
Include the steps to reproduce what you found.
System Details
Often it is nice to know, which browser you were using, version of node, platform (windows, linux). You don't need to go over the top though, for instance if you're filing a UI bug then it doesn't matter which version of node you're using.
Screenshots
Include screenshots and animated GIFs in your pull request whenever possible.
Recording GIFs There are many great tools for recording a GIF. On a mac, we recommend recordit, which is a free lightweight app.
GIF Example
Tables: When there are multiple screenshots, such as a style change that affects different themes or rtl, it can be nice to use a table for the screenshots docs
Table Example
| Firebug | Light |
|---|---|
 |
 |
|Firebug|Light|
|----------|------|
|||
If you'd like to work on an issue, /claim it in the issue and it'll be marked in-progress.
- We'll check up regularly to see how it's progressing and if we can help
- Don't hesitate to ask questions on the issue or in our Slack channel. Communication is the most important part. Don't worry about over communicating!
- Don't feel bad taking yourself off the issue if you no longer have the time or interest in the issue.
These are the labels we use to help organize and communicate the state of issues and pull requests in the project. If you find a label being used that isn't described here please file an issue to get it listed.
| Label name | query:mag_right: | Description |
|---|---|---|
available |
search | Good for contributors to work on |
difficulty:easy |
search | Work that is small changes, updating tests, updating docs, expect very little review |
difficulty:medium |
search | Work that adapts existing code, adapts existing tests, expect quick review |
difficulty:hard |
search | Work that requires new tests, new code, and a good understanding of project; expect lots of review |
docs |
search | Issues with our documentation |
design |
search | Issues that require design work |
enhancement |
search | Requests for features |
bug |
search | Reported Bugs with the current code |
chrome |
search | Chrome only issues |
firefox |
search | Firefox only issues |
infrastructure |
search | Issues with testing / build infrastructure |
discussion |
search | Issues need clearer requirements before work can be started |
needs-description |
search | Issue needs a clear description and code sketch so a contributor can work on it |
needs-str |
search | Issue needs a clear STR so that others can reproduce |
needs-investigation |
search | Issue needs to be researched |
available issues have clear requirements and a difficulty level.
They often have a patch, which should be a good starting off point. Sometimes the patches are enough to fix the bug!
One reason we file available issues when the solution is somewhat simple is that it's great to get a second set of eyes. Running the fix locally and QAing it thoroughly is a huge help. A lot of times you'll discover things that we missed.
Triaging is the act of reviewing the open issues and making sure they're up to date. It's one of the most helpful ways to help a project.
There are a couple of ways to think about it:
- it's great to be able to close issues that are done or stale
- it's great to make issue descriptions as clear as possible. Our goal is for every issue to be
availablei.e. it's clear what needs to be done. - it's really helpful to double check a new bug and see if you can reproduce it.
- it's great to ask questions that help make the issue available or call out vague issues.
- it's great to sort the issues by oldest first and help make stale issues available.
- Issues that are not likely to be worked on in the next 6 weeks will be closed and documented in the bugs or enhancements.
- Issues will often be grouped in tracking issues around shippable goals.
- Current work is included in 2 week sprint milestones
- The roadmap document is updated at the beginning of every sprint, with our current progress and realistic expectations.
When triaging, you can think of the following description as a guide: a triaged issue is:
- no more than 6 weeks old
- in line with the goals of the debugger
- a single bigger issue that is still manageable
or a set of smaller issues around a shippable goal (for example, transition the code base to JSX from
dom.divsyntax) - labeled (see Labels for more info)
- ready to be worked on, or has a request for more information or has a clear next step
An issue that does not fulfill those traits should probably be moved to one of the boards and closed.
In addition to labels and components, we use a couple of boards to organize our work.
Features features a prioritized list of features that are planned or in progress. The features are often tracking issues.
Bugs bugs a prioritized list of reported bugs.
Enhancements enhancements-board a list of feature suggestions that are reviewed twice a quarter.
We focus on being community friendly for many reasons.
- There's an educational value in having a large community of engineers who understand DevTools.
- There's an incredible diversity of talent to help us with topics ranging from testing to internationalization.
- Focusing on contributor experience helps us build the best development environment. For instance, if you find it's hard to describe how to make an accessibility change, maybe we should improve how we support tab navigation.