Label usage for GitHub projects (WIP)

Label usage for GitHub projects

This document describes the set of recommended labels and it’s meaning.

Important

This is work in progress

General considerations

• I am not considering automatic closing. For instance, closing an issue pending 'clarification' after some time. If needed we can deal with long issues on a case by case basis.

Analysis of labels currently used in asciidoctor/asciidoctor

Note	The term 'issue' is used as synonymous to 'subject', not as synonymous to problem.

For each label the following properties are defined:

Name

Name of the label on GitHub

When to use?

Description of when the label must be applied. Those marked with an ? are pending clarification.

Is fundamental?

Whether the label should be used across all projects or not

Actions

How to treat the issue once it’s been label

Notes

Personal notes for discussion

Name	When to use?	Is fundamental?	Actions	Notes
bug	Malfunctions that should be fixed to comply with the expected behavior	Yes	Close once the PR has been merged (same for [bug], [enhancement], [hackfest], [infrastructure], [design])
duplicate	Duplicated issue	Yes	Closed after a reference to the original issue has been added as a comment
enhancement	Request for improvement: either for a existing feature or a new one	Yes	Close once the PR has been merged (same for [bug], [enhancement], [hackfest], [infrastructure], [design])
clarification	Pending of response from creator or other parts	No	Keep open until response, then, add appropriate label	We can remove this, since any unlabeled issue is inherently pending of clarification
wontfix	Feature requests that don’t align with desired design. Or, in case of malfunction, no solution is available or desired.	Yes	Close after clarifying why
tracking	The issue depends on another issue or subject	Yes	State the tracked subject on a comment
compliance	Used in the past to track issues with being compliant with AsciiDoc python. No	No	Applies to asciidoctor (core) project
next	Issues that we want to cover soon but aren’t sure where exactly to put them.	No	To indicate that there is no confirmed release milestone	I think we could skip this one, unless what we want to point out that the issue has higher priority than others and should be included in the following milestone. But still, in that case we can use milestones.
documentation	Improvements or corrections over documentation. May also include improvements in documentation generation	Yes		I guess we can skip this in asciidoctor.org
github	Related to GitHub native conversion of AsciiDoc in repositories	No		Only applies to asciidoctor (core) project
relocated	Issue is not in the proper project	Yes	Close after moving the issue, current moving = closing & opening a copy (consider using github-issue-mover)
improvement	see [enhancement]			Should we keep enhancement and improvement? Since GitHub add both by default I feel like I am missing something, but for me they are the same
withdrawn	Skipped issue (similiar to [wontfix])	No	same as [wonfix]	We can just use [wontfix]. We could just use one of them
blocker	Issues or features that are required for a release	Yes	Close once the PR has been merged (same for [bug], [enhancement], [hackfest], [infrastructure], [design])
hackfest	Requires a complex solution	No	Close once the PR has been merged (same for [bug], [enhancement], [hackfest], [infrastructure], [design])	Consider adding newcomer friendly as counterpart to this instead of help wanted. I like more how it sound (idea taken from the jruby-gradle-plugin).
featured	Specially important new features or corrections	No		Could be used to highlight this issue in release notes
feedback	?		same as [clarification]?
wip (work in progress)	Solutions requires several tasks. It may aggregate several other issues and many PR’s	No		We may consider breaking it into other issues and avoid big ones
unknown	To mark an issue as something to look into further	No		I think we can skip this one, while investigating we can just mark an issue without labels (in fact, there are 0 issues in asciidoctor project
infrastructure	Related to infrastructure: CI, building, releasing, etc.	Yes	Close once the PR has been merged (same for [bug], [enhancement], [hackfest], [infrastructure], [design])	Not very used, but imo fundamental
design	Solution requires a deep analysis of alternatives	No		Close once the PR has been merged (same for [bug], [enhancement], [hackfest], [infrastructure], [design])

Other labels

Here are labels not included in asciidoctor/asciidoctor but that can be useful to have.

Name	When to use?	Is fundamental?	Actions	Notes
invalid	In case of malfunction reported is confirmed not to be such	Yes		It is already provided by GitHub
support	Questions and doubts related to the use of the tools, syntax, features, etc.	Yes	Close after the creator confirms it’s solved