Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Document GitHub labels #8642
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:
Labels I think I have properly documented, but reviews and suggested improvements are welcome:
Thanks so much for the input on this facchinm and matthijskooijman!
Based on facchinm's information, I propose the following:
as well as using facchinm's descriptions of
Responses to matthijskooijman's comments:
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 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
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).
I review all incoming issues so I could add the
Thanks! That was definitely a brain glitch or copy paste error on my part. I propose the following:
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.
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:
The descriptions above are all as previously discussed except for the following:
I'm also requesting permission to make the following changes:
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:
@facchinm, I think it's up to you to make the final call and approve this :-)
I agree that the
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.