Document GitHub labels

[per1234]

I really like the use of GitHub labels on issues and pull requests because it can make it easier to find what you're looking for out of the thousands of issues and PRs this repo has.

I try to be diligent about labeling issues, but the meaning or intent of some of the labels is not clear to me. This makes me think it would be beneficial (for me as well as other users of the issue tracker) to document the meaning of the labels. I have made an attempt to document each label in the lists below. I would appreciate help with the first list and any review/suggestions/confirmation of the second list.

I propose that once the descriptions are verified, they be added as "descriptions" in the GitHub Label configuration page. The descriptions appear as a tooltip when you hover the mouse over a label.

---

Labels I need help with:

Label	Proposed Description	Notes
Component: Core	TODO	It's not clear to me what the meaning of this is. The term "core" is used several ways by Arduino. It could mean all of Arduino AVR Boards (what I used to call a "hardware package"), or just the contents of the cores subfolder of Arduino AVR Boards (what I call a "core library"). I also see the Arduino IDE source code has a folder named arduino-core.
Component: Firmware	TODO	Is this limited to the contents of the firmwares folder in the core packages (e.g. https://github.com/arduino/ArduinoCore-avr/tree/master/firmwares)?
Component: USB Device	TODO	The specific meaning of this is not clear to me
feature request	Requests to add a feature to the Arduino IDE	Is this redundant to Type: Improvement? If so, I would like to relabel all items that use it and then delete this label.
Proposal	TODO	Is this redundant to Type: Improvement? If so, I would like to relabel all items that use it and then delete this label.
Type: Improvement	Proposals or requests for improvements	The inconsistent use of this label makes it seem like it might be used to indicate the perceived merit of a feature request. I see that the majority of valid issue reports fall into one of two categories: bug report, and feature request. I think having a consistently used label for each of these categories (regardless of how beneficial the feature requests are considered to be) would be extremely helpful in searching the tracker. I propose to use this label for all feature requests and the Type: Bug label for all bug reports. If you do want to use Type: Improvement as an indicator of merit, then perhaps one of the other labels (feature request, proposal) I consider possibly redundant to this label could be used for all feature requests.
Uncategorized	Labeling of this item has not yet occurred	This label seems unnecessary, and has not been used for years. I propose that I label all issues that have this label and then delete it.
libListSerial	Java library used in the Arduino IDE's source code to find serial ports on the computer	Is the description correct (it's only a guess)?
Type: Regression	TODO	Anyone have a concise description of what a regression is in this context?

---

Labels I think I have properly documented, but reviews and suggested improvements are welcome:

Label	Proposed Description	Notes
32bit Deprecation	Starting with macOS 10.15, 32-bit applications will not be supported
accessibility	Enabling the use of the software by everyone
Architecture: AVR	Applies only to the AVR microcontrollers (Uno, etc.)
Architecture: SAM	Applies only to the SAM microcontrollers (Due)
Architecture: SAMD	Applies only to the SAMD microcontrollers (Zero, etc.)
arduino-builder	Applies only to the AVR microcontrollers
arduino-cli	Related to the arduino-cli tool
Board: Arduino Due	Applies only to the Due
Board: Arduino Robot	Applies only to the Arduino Robot
c++14	Related to switching to use of the C++14 standard
Component: Avrdude 6.3	Specific to AVRDUDE version 6.3
Component: Board/Lib Manager	Boards Manager or Library Manager
Component: Bootloader	The bootloader is the program used to load the uploaded program into the microcontroller's memory
Component: CLI	The Arduino IDE's command line interface
Component: Compilation	Related to compilation of Arduino sketches
Component: Documentation	Related to Arduino's documentation content
Component: Hardware	Related to the design of Arduino's hardware products
Component: HardwareSerial	The hardware serial functionality of the core libraries
Component: IDE Serial monitor	Tools > Serial Monitor
Component: IDE user interface	The Arduino IDE's user interface
Component: IDE	The Arduino IDE
Component: Preprocessor	The Arduino sketch preprocessor converts .ino files into C++ code before compilation
Component: Proxy	The Arduino IDE's support for connection to the Internet via a proxy server
Component: Toolchain	The tools used for compilation and uploading to Arduino boards
Component: Uploading	Uploading programs to an Arduino board
Component: Website	Issues related to arduino.cc
Drivers	Drivers used to support Arduino boards on the computer
editor-refactor	Related to the refactoring of the Arduino IDE's editor component
Examples: ArduinoISP	The ArduinoISP example sketch
Help wanted	Arduino would especially appreciate assistance from the community on this item
IDE 1.9.x Beta	Related to the Arduino IDE Beta Build
in progress	Work on this item is in progress
Java 9+	Related to porting the Arduino IDE to use Java version 9 or newer
jmdns	Multi-cast DNS Java library used in the Arduino IDE's source code
Library: Bridge	The Bridge Arduino library
Library: EEPROM	The EEPROM Arduino library
Library: Ethernet	The Ethernet Arduino library
Library: HID	The HID Arduino library
Library: LiquidCrystal	The LiquidCrystal Arduino library
Library: Other	Arduino libraries that don't have their own label
Library: Scheduler	The Scheduler Arduino library
Library: SD	The SD Arduino library
Library: Servo	The Servo Arduino library
Library: SoftwareSerial	The SoftwareSerial Arduino library
Library: SPI	The SPI Arduino library
Library: Stepper	The Stepper Arduino library
Library: TFT	The TFT Arduino library
Library: Wifi	The Wifi Arduino library
Library: Wire	The Wire Arduino library
Localization	Adding support for specific regions or languages to the Arduino IDE
On Hold	The pull request is blocked from being merged
OS: Linux ARM	Specific to the Linux ARM version of the Arduino IDE
OS: Linux	Specific to the Linux version of the Arduino IDE
OS: OSX	Specific to the Max OS X (macOS) version of the Arduino IDE
OS: Windows XP	Specific to the Arduino IDE running on Windows XP
OS: Windows	Specific to the Windows version of the Arduino IDE
Print and Stream class	The Arduino core library's Print and Stream classes
question	A request for information
theme	The Arduino IDE's theme system
Type: Bug
Type: Duplicate	Another item already exists for this topic
Type: Invalid	Off topic for this repository, or a bug report determined to not actually represent a bug
Type: Wontfix	Arduino has decided that it will not resolve the reported issue or implement the requested feature
Type: Works For Me	We are unable to reproduce the reported bug
Upstream notified	This item is related to a software component maintained by someone else, and they have been notified of it
USB: CDC serial	The serial interface used by microcontrollers with native USB functionality (e.g. Leonardo) to communicate with the computer
Waiting for feedback	More information must be provided before we can proceed
windows store app	The Windows app version of the Arduino IDE from the Microsoft Store

[facchinm]

Label	Proposed Description
Component: Core	By looking at the issues tagged as core, they are all related with API bugs/feature requests, so they better fit https://github.com/arduino/ArduinoCore-api in the new structure
Component: Firmware	Limited to the contents of the firmwares folder in the core packages (e.g. https://github.com/arduino/ArduinoCore-avr/tree/master/firmwares) and bootloaders. Need a bit of review
Component: USB Device	Opposed to USB Host, contains bugs or feature request that apply to USB subsystem (SerialUSB, HID, ...)
feature request	I'd keep one between this and Proposal, since tagging as Improvement makes it difficult to understand that state of the issue/PR
Type: Improvement	Can be used as an indicator of merit if a proposal is very interesting
Uncategorized	Can be safely removed I think
libListSerial	Java native library used in the Arduino IDE's source code to find serial ports on the computer
Type: Regression	Something that used to work and now doesn't 🙂

[matthijskooijman]

Label	Proposed Description
Component: Core	I would think this refers to the code running on an arduino, e.g. most of the "hardware" directory. In practice, all of this code was moved to different repositories now, so I think this label has no place here anymore (at least not for new issues).
Type: Improvement	Hm, I think I would have seen this as a "new feature" / feature request (as opposed to a bug report). I'm not sure if there's any point in having a label for "This request/proposal has merit" (instead, we should just close issues that are pointless...).
Proposal	This could be distinct from a feature request, in the sense that a feature request describes the wanted end result, whereas a proposal describes a possible implementation to get to an end result. In that sense it can be useful to tag these, since proposals might require a different kind of review, though I suspect that this won't be used much in practice. I'd be in favor of removing this label.
feature request	A downside of the "Feature request" label is that it implies that someone makes a request. Proposing a new feature could be considered to not fall under this label. Requesting some improvement that is not really a "feature" per se (but also not a bugfix) could be considered not to fall under this label. I think I might have introduced "Type: Improvement" a long time ago to resolve these two things (as an umbrella label for all improvements, features and proposals that are not bugs).
Uncategorized	Can be safely removed I think. One reason to have it is you can keep an explicit labeling todo-list, but that only really works if all new issues get the Uncategorized label by default (which I do not think github supports).
Type: Regression	I think regressions are good to separately label, but they are hard to define. Pretty much any bug is often a regressions, except for the things that never worked from when they were added. However, a regression is often a side effect of some other improvement or fix and since it used to work, a (recent) regression often has a bit more priority over bugs that have always been broken (or at least for quite some while).

Furthermore:

• Your proposal for arduino-builder seems wrong.
• I think we should remove the two Board labels, since there are dozens of boards, so no point to keep labels for each (and what makes these two special?).
• "Component: CLI" should probably be renamed to "Component: IDE CLI", to disambiguate from arduino-cli and arduino-builder.
• Some of the labels could use a prefix (mostly "Component: " I think) and/or capitalization.

[per1234]

Thanks so much for the input on this facchinm and matthijskooijman!

Based on facchinm's information, I propose the following:

Label	Proposed Description
Component: Core	Related to the code for the standard Arduino API

as well as using facchinm's descriptions of Component: Firmware, Component: USB Device, libListSerial, and Type: Regression.

---

Responses to matthijskooijman's comments:

[re: Component: Core] I would think this refers to the code running on an arduino, e.g. most of the "hardware" directory. In practice, all of this code was moved to different repositories now, so I think this label has no place here anymore (at least not for new issues).

The valid reason I could see for someone submitting an issue to this repository regarding the core is when the issue is not architecture specific and also isn't about the code in the ArduinoCore-API repository. Since this repository acts as the catch-all for issues that don't fit in any of the other repositories, it is reasonable to submit those issues here. The alternative would be to submit them to the Arduino AVR Boards repository and consider that to be the catch-all for that type of issue.

Regarding labels that have no more use for new issues: It would be kind of nice to clear out the label list a bit, but I wouldn't like to see labels removed from old issues when they are useful for searching those issues. It might make sense to somehow indicate in the label description when a label is "dead". The alternative is to move those issues (including the closed ones) to the appropriate repositories. I think that would be very worthwhile, and I would be happy to do this, but it doesn't seem to be possible to do currently using GitHub's issue transfer system (see #8245). The issues could be manually moved, and then the labels removed from the moved issues, but it would be better to figure out how to do it the GitHub way. Since GitHub doesn't allow transfers between organizations, some manual moving might be necessary anyway.

I'm not sure if there's any point in having a label for "This request/proposal has merit" (instead, we should just close issues that are pointless...).

I don't think I'm qualified to make a judgement call on the relative merit of feature requests and PRs (other than when it's obviously invalid) so I don't see myself using a label with that function. However, if the more qualified members of the team want a label for that use, I'm fine with it. It might be more self-documenting if it was called something like Priority: High (which could be used for bug reports as well). I hope that feature requests with no merit are being closed already. Of the valid ones, there is a spectrum between "That would be nice, but it's not going to be a priority. Maybe someone from the community will submit a PR." and "We really need to do this as soon as possible.".

I think I might have introduced "Type: Improvement" a long time ago to resolve these two things (as an umbrella label for all improvements, features and proposals that are not bugs).

That is exactly what I want: an umbrella label for all of that. I think being able to split almost all the issues into one of two broad categories could be really helpful for searches. I will often know which of the two categories the thing I'm looking for falls under. If I can filter out the other category, that means a lot less search results to look through when the query has a lot of matches. Although Library Manager inclusion requests technically fall into the "improvement" category, I would leave these out (and preferably give them a dedicated label).

that only really works if all new issues get the Uncategorized label by default (which I do not think github supports).

I review all incoming issues so I could add the Uncategorized label to any that I'm not able to otherwise label if that was considered desirable. I think it will be less common for me to not be able to add at least one label for each issue now that I'm getting a better understanding of what all the labels mean.

Your proposal for arduino-builder seems wrong.

Thanks! That was definitely a brain glitch or copy paste error on my part. I propose the following:

Label	Proposed Description
arduino-builder	The tool used to handle the Arduino sketch compilation process

Some of the labels could use a prefix (mostly "Component: " I think) and/or capitalization.

I agree that it would be nice to standardize the labels more (within this repo as well as across all the Arduino repos). That's something I have somewhere on my "to-do" list. It's probably worth making a dedicated issue report for that proposal.

[per1234]

Since there hasn't been any new input in the last few weeks, I'd like to try to move forward with this project.

I'm requesting approval to add the following descriptions to this repository's labels:

Label	Proposed Description
32bit Deprecation	Starting with macOS 10.15, 32-bit applications will not be supported
accessibility	Enabling the use of the software by everyone
Architecture: AVR	Applies only to the AVR microcontrollers (Uno, etc.)
Architecture: SAM	Applies only to the SAM microcontrollers (Due)
Architecture: SAMD	Applies only to the SAMD microcontrollers (Zero, etc.)
arduino-builder	Applies only to the AVR microcontrollers The tool used to handle the Arduino sketch compilation process
arduino-cli	Related to the arduino-cli tool
Board: Arduino Due	Applies only to the Due
Board: Arduino Robot	Applies only to the Arduino Robot
c++14	Related to switching to use of the C++14 standard
Component: Avrdude 6.3	Specific to AVRDUDE version 6.3
Component: Board/Lib Manager	Boards Manager or Library Manager
Component: Bootloader	The bootloader is the program used to load the uploaded program into the microcontroller's memory
Component: CLI	The Arduino IDE's command line interface
Component: Compilation	Related to compilation of Arduino sketches
Component: Core	Related to the code for the standard Arduino API
Component: Documentation	Related to Arduino's documentation content
Component: Firmware	Limited to the contents of the firmwares folder in the core packages (e.g. https://github.com/arduino/ArduinoCore-avr/tree/master/firmwares)
Component: Hardware	Related to the design of Arduino's hardware products
Component: HardwareSerial	The hardware serial functionality of the core libraries
Component: IDE Serial monitor	Tools > Serial Monitor
Component: IDE user interface	The Arduino IDE's user interface
Component: IDE	The Arduino IDE
Component: Preprocessor	The Arduino sketch preprocessor converts .ino files into C++ code before compilation
Component: Proxy	The Arduino IDE's support for connection to the Internet via a proxy server
Component: Toolchain	The tools used for compilation and uploading to Arduino boards
Component: Uploading	Uploading programs to an Arduino board
Component: USB Device	Opposed to USB Host, contains bugs or feature request that apply to USB subsystem (SerialUSB, HID, ...)
Component: Website	Issues related to arduino.cc, but not the documentation content
Drivers	Drivers used to support Arduino boards on the computer
editor-refactor	Related to the refactoring of the Arduino IDE's editor component
Examples: ArduinoISP	The ArduinoISP example sketch
feature request	A request to make an enhancement (not a bug fix)
Help wanted	Arduino would especially appreciate assistance from the community on this item
IDE 1.9.x Beta	Related to the Arduino IDE Beta Build
in progress	Work on this item is in progress
Java 9+	Related to porting the Arduino IDE to use Java version 9 or newer
jmdns	Multi-cast DNS Java library used in the Arduino IDE's source code
libListSerial	Java native library used in the Arduino IDE's source code to find serial ports on the computer
Library: Bridge	The Bridge Arduino library
Library: EEPROM	The EEPROM Arduino library
Library: Ethernet	The Ethernet Arduino library
Library: HID	The HID Arduino library
Library: LiquidCrystal	The LiquidCrystal Arduino library
Library: Other	Arduino libraries that don't have their own label
Library: Scheduler	The Scheduler Arduino library
Library: SD	The SD Arduino library
Library: Servo	The Servo Arduino library
Library: SoftwareSerial	The SoftwareSerial Arduino library
Library: SPI	The SPI Arduino library
Library: Stepper	The Stepper Arduino library
Library: TFT	The TFT Arduino library
Library: Wifi	The Wifi Arduino library
Library: Wire	The Wire Arduino library
Localization	Adding support for specific regions or languages to the Arduino IDE
On Hold	The pull request is blocked from being merged
OS: Linux ARM	Specific to the Linux ARM version of the Arduino IDE
OS: Linux	Specific to the Linux version of the Arduino IDE
OS: OSX	Specific to the Max OS X (macOS) version of the Arduino IDE
OS: Windows XP	Specific to the Arduino IDE running on Windows XP
OS: Windows	Specific to the Windows version of the Arduino IDE
Print and Stream class	The Arduino core library's Print and Stream classes
question	A request for information
theme	The Arduino IDE's theme system
Type: Bug
Type: Duplicate	Another item already exists for this topic
Type: Improvement	This proposal is considered to be especially beneficial
Type: Invalid	Off topic for this repository, or a bug report determined to not actually represent a bug
Type: Regression	Something that used to work and now doesn't
Type: Wontfix	Arduino has decided that it will not resolve the reported issue or implement the requested feature
Type: Works For Me	We are unable to reproduce the reported bug
Uncategorized	Labeling of this item has not yet occurred
Upstream notified	This item is related to a software component maintained by someone else, and they have been notified of it
USB: CDC serial	The serial interface used by microcontrollers with native USB functionality (e.g. Leonardo) to communicate with the computer
Waiting for feedback	More information must be provided before we can proceed
windows store app	The Windows app version of the Arduino IDE from the Microsoft Store

The descriptions above are all as previously discussed except for the following:

Label	Proposed Description
feature request	A request to make an enhancement (not a bug fix)
Type: Improvement	This proposal is considered to be especially beneficial

I'm also requesting permission to make the following changes:

• Switch all items labeled Proposal to using the feature request label.
• Delete the Proposal label.
• Switch all items labeled Type: Improvement to using the feature request label. The reason for this is that we may have now changed the meaning of the Type: Improvement label. There is no guarantee that label was added to those items in the past with the intent of using it to indicate relative merit.

[matthijskooijman]

This one fell off my radar. Just read your previous comment from a few weeks ago, agreed on all points. Your proposal in the last comment looks good, except:

• You mislabeled arduino-builder again :-p
• I would suggest also deleting the Type: Improvement again, since I see little merit and it would remain somewhat confusing next to the feature request label.
• I would suggest also renaming the feature request label to Type: Feature Request, so everything that's valid can be in either of those two categories, as you previously suggested.

@facchinm, I think it's up to you to make the final call and approve this :-)

[per1234]

You mislabeled arduino-builder again :-p

Thanks again!

I would suggest also deleting the Type: Improvement again, since I see little merit and it would remain somewhat confusing next to the feature request label.

I agree that the Type: Improvement label name does not make its purpose clear. My plan was to propose to rename Type: Improvement to Priority: High, along with some other label names changes, in a separate issue report. The reason for this is that I feel discussion of the enhancement labels seems to have the potential to stall progress on the real goal of this issue report, so I thought I'd just stick with exactly what facchinm approved for now.

I would suggest also renaming the feature request label to Type: Feature Request, so everything that's valid can be in either of those two categories, as you previously suggested.

I'm in agreement with this too, but I want to deal with those types of changes comprehensively in a separate issue report so that this one can have a better chance of accomplishing the single goal of adding descriptions to the GitHub labels.

[matthijskooijman]

Ok, that makes sense. In that case, I think @facchinm has already approved your proposal with a thumbs up, so I think it's good to execute it :-)

[facchinm]

Thumbs up 😄

[per1234]

OK, the label descriptions project is now finished. Thanks so much for the assistance matthijskooijman and facchinm!

I'll open a new issue proposing to rename some labels, with the information from the discussion on that topic we had here, soon.