You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Firefox Debugger is constantly evolving. Our community team is regularly **fixing bugs**, **adding features**, **improving documentation**, and **coming up with ideas for future versions**.
4
+
5
+
You, too, can be a part of this process by **creating an issue** in this repository.
6
+
7
+
Do this whenever you'd like to suggest a fix or make a change.
8
+
9
+
To learn how to create an issue on GitHub, [click here][issue-docs].
10
+
11
+
### Table of Contents
12
+
3
13
*[Issue Titles](#issue-titles)
4
14
*[Issue Descriptions](#issue-descriptions)
5
15
*[Claiming Issues](#claiming-issues)
@@ -13,18 +23,22 @@
13
23
14
24
**Components**
15
25
16
-
Issues are organized in terms of components.
17
-
Issue titles should include the name of the component as a tag
18
-
at the very beginning. Consider the following titles:
26
+
To keep our issues organized, we like to categorize them according to which [component][component-docs] they fix or modify.
27
+
28
+
The first step in this categorization process is the **issue title**, which you create when opening an issue for the first time.
29
+
30
+
Here are examples of what we consider to be *good* and *bad* issue titles.
19
31
20
32
* Bad: `Fix input field padding of search bar`
21
33
* Good: `[SearchBar] Fix input field padding`
22
34
23
-
or
24
-
25
35
* Bad: `Add information about titles to documentation`
26
36
* Good: `[Docs] Add information about titles`
27
37
38
+
Did you spot the differences?
39
+
40
+
When you submit an issue, **the title of the issue should begin with a tag**, placed within brackets (\[\]). The tag should reference the most relevant component for the code change you suggest.
41
+
28
42
Some common tags include:
29
43
30
44
|Editor|SecondaryPanes|UI|Other|
@@ -35,35 +49,55 @@ Some common tags include:
35
49
|SourceFooter|CallStack||Action|
36
50
||Scopes||Docs|RTL|
37
51
38
-
39
52
**User Perspective**
40
53
41
-
The best issue titles are framed in terms of the impact on the user. i.e.
54
+
There's more to an issue title than just the component tag, of course.
55
+
56
+
Once you've written out your tag, you need to write a few words to explain:
57
+
* The bug you've discovered
58
+
* The feature you're recommending
59
+
* The change you would like to see made to the project
42
60
43
-
*`[Editor] search skips odd matches`
44
-
*`[WatchExpressions] can't remove an expression after it's been edited`
61
+
The best issue titles take the above details and frame them in terms of their **impact on the user**.
45
62
46
-
Things to try and avoid in the title
47
-
* implementation details where possible. Refactoring is an exception where it's okay
48
-
* vague language like e.g "debugger crashes", "can't install"
49
-
* 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.
63
+
For example:
64
+
65
+
*`[Editor] Search skips odd matches`
66
+
*`[WatchExpressions] Can't remove an expression after it's been edited`
67
+
68
+
In addition to including the above details (i.e. component tag, user impact), the best issues also **exclude information that is unhelpful or irrelevant to contributors** that are reading the issue list.
69
+
70
+
Here is a list of a few **things you should avoid** in your issue titles:
71
+
* Implementation details, where possible. Refactoring is an exception where this is permitted.
72
+
* Vague language (e.g. "debugger crashes", "can't install").
73
+
* Negative language (e.g. "Search is terrible").
50
74
51
75
52
76
### Issue Descriptions
53
77
54
-
**Steps to Reproduce***STR*
78
+
**Steps to Reproduce****(STR)**
79
+
80
+
Before an issue can be resolved, other contributors must first be able to reproduce it accurately.
55
81
56
-
Include the steps to reproduce what you found.
82
+
When you file an issue, be sure to **include a list of all of the steps necessary to reproduce the bug** or problem that you have found. Try to be as specific as possible.
57
83
58
84
**System Details**
59
85
60
-
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.
86
+
All bugs are not reproducible in all environments. If you experience a bug, please include a list of your specific system details in the issue. This can help others reproduce the bug, and help them check if it can be reproduced on other systems, as well.
87
+
88
+
Include system details such as:
89
+
90
+
* Which **browser** (and browser version) you were using when the bug occurred
91
+
* What **platform** (Windows, Mac, Linux) you were using to run the browser
92
+
* Which **version of Node** you have installed.
93
+
94
+
**Note:** You don't need to mention system details that are irrelevant to the bug you have found. For example, if you're filing an issue about a bug in the UI, there's no need to include which version of Node you're using.
61
95
62
96
**Screenshots**
63
97
64
-
Include screenshots and animated GIFs in your pull request whenever possible.
98
+
Whenever possible, please **include screenshots and/or animated GIFs** in the issues you open.
65
99
66
-
**Recording GIFs** There are many great tools for recording a GIF. On a mac, we recommend [recordit](http://recordit.co/), which is a free lightweight app.
100
+
Click the dropdown arrow below to see an example of such a GIF:
67
101
68
102
<details>
69
103
<summary>
@@ -75,10 +109,21 @@ Include screenshots and animated GIFs in your pull request whenever possible.
75
109
```
76
110
77
111
```
78
-
79
112
</details>
80
113
81
-
**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][github-tables]
114
+
#### Tools for Recording GIFs
115
+
116
+
There are many **free tools** available that will allow you to record a GIF of the problem or bug you are referencing in your issue.
117
+
118
+
For **Mac** and **Windows** users, we recommend [recordit](http://recordit.co/).
119
+
120
+
For **Linux** users, we recommend [Peek](https://github.com/phw/peek).
121
+
122
+
#### Tables
123
+
124
+
In cases where multiple screenshots are necessary to demonstrate a bug (e.g. style issues that affect multiple themes, rtl vs. ltr errors, etc.), we recommend that you **use a table in your issue to keep everything organized**.
125
+
126
+
[Click here][github-tables] to learn more about organizing information with tables on GitHub.
82
127
83
128
<details>
84
129
<summary>
@@ -100,11 +145,14 @@ Include screenshots and animated GIFs in your pull request whenever possible.
100
145
101
146
### Claiming Issues
102
147
103
-
If you'd like to work on an issue, `/claim` it in the issue and it'll be marked `in-progress`.
148
+
If you'd like to work on an issue, simply comment `/claim` on the issue thread. A bot will then mark the issue as `in-progress`, and you can begin your work.
149
+
150
+
When you claim an issue, keep the following in mind:
151
+
152
+
* Don't hesitate to ask questions on the issue or in our Slack channel. Communication is the most important part of the development process, so don't worry about over-communicating!
153
+
* Don't feel bad about taking yourself off of an issue if you no longer have the time or interest necessary to tackle it.
104
154
105
-
* We'll check up regularly to see how it's progressing and if we can help
106
-
* 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!
107
-
* Don't feel bad taking yourself off the issue if you no longer have the time or interest in the issue.
155
+
Once you've claimed your issue, our maintainers will check up regularly to see how it's progressing. They'll offer help, too, if you need it.
108
156
109
157
110
158
![cl]
@@ -113,111 +161,90 @@ If you'd like to work on an issue, `/claim` it in the issue and it'll be marked
113
161
114
162
### Labels
115
163
164
+
As an active repository, it is quite normal for _debugger_ to have a wide variety of issues open at any one time.
116
165
117
-
These are the [labels](https://github.com/firefox-devtools/debugger/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.
118
-
119
-
| Label name | query:mag_right:| Description |
120
-
| --- | --- | --- |
121
-
|`available`|[search][labels-available]| Good for contributors to work on |
122
-
|`difficulty:easy`|[search][labels-difficulty-easy]| Work that is small changes, updating tests, updating docs, expect very little review |
123
-
|`difficulty:medium`|[search][labels-difficulty-medium]| Work that adapts existing code, adapts existing tests, expect quick review |
124
-
|`difficulty:hard`|[search][labels-difficulty-hard]| Work that requires new tests, new code, and a good understanding of project; expect lots of review |
125
-
|`docs`|[search][labels-docs]| Issues with our documentation |
126
-
|`design`|[search][labels-design]| Issues that require design work |
127
-
|`enhancement`|[search][labels-enhancement]|[Requests](../.github/CONTRIBUTING.md#suggesting-enhancements-new) for features |
128
-
|`bug`|[search][labels-bug]|[Reported Bugs](../.github/CONTRIBUTING.md#reporting-bugs-bug) with the current code |
129
-
|`chrome`|[search][labels-chrome]| Chrome only issues |
130
-
|`firefox`|[search][labels-firefox]| Firefox only issues |
131
-
|`infrastructure`|[search][labels-infrastructure]| Issues with testing / build infrastructure |
132
-
|`discussion`|[search][labels-discussion]| Issues need clearer requirements before work can be started |
133
-
|`needs-description`|[search][labels-needs-description]| Issue needs a clear description and code sketch so a contributor can work on it |
134
-
|`needs-str`|[search][labels-needs-str]| Issue needs a clear STR so that others can reproduce |
135
-
|`needs-investigation`|[search][labels-needs-investigation]| Issue needs to be researched |
166
+
To keep things organized, our goal is to assign every issue a **label**.
136
167
168
+
These labels act as categorization tools. They help our contributors understand important details about an issue at a glance. These details include issue type (*bug*, *enhancement*, etc.) and issue status (*available*, *not-available*, etc.), along with other important information.
137
169
170
+
To see the **current list of active labels** in the *debugger* repository, [click here][labels-list].
138
171
139
172
### Available Issues
140
173
141
-
[available][labels-available] issues have clear requirements and a difficulty level.
174
+
[Available][labels-available] issues have clear requirements and a difficulty level.
142
175
143
176
They often have a patch, which should be a good starting off point.
144
-
Sometimes the patches are enough to fix the bug!
177
+
Sometimes, the patches themselves are enough to fix the bug!
145
178
146
-
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.
179
+
One reason we file `available` issues when the solution is somewhat simple, is because it's helpful to get a second set of eyes on them problem. Running the fix locally and QAing it thoroughly is a huge help. A lot of times, you'll discover things that we missed.
147
180
148
181
### Triaging
149
182
150
-
Triaging is the act of reviewing the open issues and making sure they're up to date.
151
-
It's one of the most helpful ways to help a project.
183
+
Triaging is the act of **reviewing open issues and making sure they're up to date**. Triaging issues is an extremely important task, and can contribute greatly to the overall health of the project.
184
+
185
+
Here are a few ways you can help triage our *Issues* list:
152
186
153
-
There are a couple of ways to think about it:
154
-
* it's great to be able to close issues that are done or stale
155
-
* it's great to make issue descriptions as clear as possible. Our goal is for every issue to be `available` i.e. it's clear what needs to be done.
156
-
* it's really helpful to double check a new bug and see if you can reproduce it.
157
-
* it's great to ask questions that help make the issue available or call out vague issues.
158
-
* it's great to sort the issues by oldest first and help make stale issues available.
187
+
* Sort issues by *Oldest* first, and work through stale issues to make them `available`
188
+
* Ask questions and clarify issues in order to help make them `available` (i.e they have a clear plan of action)
189
+
* Close issues that are done, or stale
190
+
* Check new bugs to see if they can be reproduced
191
+
* Ask questions to bring attention to vague issues
159
192
160
-
#### Process
193
+
#### Our Issue Resolution Process
161
194
162
-
1. Issues that are not likely to be worked on in the next 6 weeks will be closed and documented in the[bugs][bugs-board] or [enhancements][enhancements-board].
195
+
1. Issues that are not likely to be worked on in the next six (6) weeks will be closed and documented in [bugs][bugs-board] or [enhancements][enhancements-board].
163
196
2. Issues will often be grouped in tracking issues around shippable goals.
164
-
3. Current work is included in 2 week sprint milestones
165
-
4. The [roadmap] document is updated at the beginning of every sprint, with our current progress and realistic expectations.
197
+
3. Current work is included in two-week sprint milestones
198
+
4. The [roadmap] document is updated at the beginning of every sprint, along with our current progress and realistic expectations.
166
199
167
-
#### What is a triaged issue?
200
+
#### What is a Triaged Issue?
168
201
169
-
When triaging, you can think of the following description as a guide:
170
-
a triaged issue is:
202
+
A *triaged issue* is:
171
203
172
-
* no more than 6 weeks old
173
-
* in line with the goals of the debugger
174
-
* a single bigger issue that is still manageable
175
-
*or* a set of smaller issues around a shippable goal (for example, transition the code base to JSX from `dom.div` syntax)
176
-
* labeled (see [Labels](#labels) for more info)
177
-
* ready to be worked on,
178
-
*or* has a request for more information
179
-
*or* has a clear next step
204
+
* No more than six weeks old
205
+
* In line with the goals of *debugger*
206
+
* Labeled (see [Labels](#labels) for more info)
207
+
* Either:
208
+
* A single bigger issue that is still manageable, *or*
209
+
* a set of smaller issues, organized around a shippable goal (for example, transitioning the code base to JSX from `dom.div` syntax)
210
+
* Either:
211
+
* Ready to be worked on,
212
+
*or*
213
+
* has a request for more information,
214
+
*or*,
215
+
* has a clear next step
180
216
181
-
An issue that does not fulfill those traits should probably be moved to one of the boards and
217
+
When triaging an issue, we recommend that you use the above description as a guide.
218
+
219
+
An issue that does not fulfill the traits listed above should generally be moved to one of the boards and
182
220
closed.
183
221
184
222
### Issue Organization
185
223
186
224
In addition to labels and components, we use a couple of boards to organize our work.
187
225
188
-
**Features**[features][features-board] a prioritized list of features that are planned or in progress. The features are often tracking issues.
226
+
**[Features][features-board]** - A prioritized list of features that are either *planned* or *in progress*. The features are often tracking issues.
189
227
190
-
**Bugs**[bugs][bugs-board] a prioritized list of reported bugs.
228
+
**[Bugs][bugs-board]** - A prioritized list of reported bugs.
191
229
192
-
**Enhancements**[enhancements-board] a list of feature suggestions that are reviewed twice a quarter.
230
+
**[Enhancements][enhancements-board]** - A list of feature suggestions. We review this list twice every quarter (i.e. every three months, beginning in January).
193
231
194
232
### Community Friendly
195
233
196
234
We focus on being community friendly for many reasons.
197
235
198
236
* There's an educational value in having a large community of engineers who understand DevTools.
199
-
* There's an incredible diversity of talent to help us with topics ranging from testing to internationalization.
237
+
* There's an incredible diversity of talent that can help us with topics ranging from testing to internationalization.
200
238
* 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.
0 commit comments