Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document GitHub labels #8642

Closed
per1234 opened this Issue Mar 12, 2019 · 9 comments

Comments

3 participants
@per1234
Copy link
Collaborator

per1234 commented Mar 12, 2019

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

This comment has been minimized.

Copy link
Member

facchinm commented Mar 12, 2019

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

This comment has been minimized.

Copy link
Collaborator

matthijskooijman commented Mar 12, 2019

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

This comment has been minimized.

Copy link
Collaborator Author

per1234 commented Mar 12, 2019

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

This comment has been minimized.

Copy link
Collaborator Author

per1234 commented Apr 1, 2019

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 comment has been minimized.

Copy link
Collaborator

matthijskooijman commented Apr 1, 2019

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

This comment has been minimized.

Copy link
Collaborator Author

per1234 commented Apr 1, 2019

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

This comment has been minimized.

Copy link
Collaborator

matthijskooijman commented Apr 1, 2019

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

This comment has been minimized.

Copy link
Member

facchinm commented Apr 2, 2019

Thumbs up 😄

@per1234

This comment has been minimized.

Copy link
Collaborator Author

per1234 commented Apr 2, 2019

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.

@per1234 per1234 closed this Apr 2, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.