RFC: New issue labelling

[rdeltour]

The labels used in the issue tracker have grown organically over the years, and could be reorganized for better clarity.

Current labels

At the time of writing, the labels are:

• bug
• bugfix
• Changes API/Interface/OutputFormat
• css validation
• docs
• duplicate
• edupub
• enhancement
• epub-3.1
• has dedicate PullRequest
• imported
• invalid
• messages & localization
• missing
• needs review
• organization
• postponed
• question
• refactoring
• reviewed & ready for implementation
• spec
• waiting for feedback
• wontfix

The list is a bit heterogeneous, it contains labels identifying either the issue's status, or the topic, or its type.

Proposed labels

The idea is to organize labels into several "categories", as follow:

Status

The following labels would identify the status of the issue; they are mutually exclusive

• status: waiting for feedback indicates that the maintainers are waiting for more information from the issue's author before any further processing
• status: in discussion indicates that the maintainers are discussing the validity of the issue before accepting or rejecting it.
• status: accepted indicates that the issue is legitimate and should be processed by the development team
• status: waiting for review indicates that the envisioned solution discussed in the issue's comments needs to be further reviewed before being implemented
• status: ready for implem indicates that the issue is ready to be worked on (e.g. a bug fix or new feature is ready to be implemented)
• status: in progress indicates that the issue is being worked on
• status: has pull request indicates that the issue has an associated pull request; further discussion may happen directly on the pull request
• status: blocked indicates that the issue is blocked by something else (like another issue, or a spec issue)
• status: completed indicates that the work on the issue is done, and the issue can be closed
• status: stalled  indicates that the issue hasn't been active for a while (exact duration of inactivity tbd)

Additionally, pull requests can have the following status:

• status: waiting for review indicates that the PR is ready for reviewers
• status: ready to merge indicates that the PR is ready to be merged in the master branch

Types

The following labels would identify the nature of the issue:

• type: bug the issue describes a bug
• type: feature the issue describes a new feature request
• type: improvement the issue describes a potential improvement (refactoring, better implementation, etc) of an existing feature
• type: chore the issue is related to a meta task like the build system, code generation, minor dependency updates, etc.
• type: test the issue is related to the test suite
• type: docs the issue is related to the documentation
• type: invalid the issue has been deemed invalid by the maintainers (e.g. a request for support), and will be rejected
• type: duplicate the issue duplicates an existing issue
• type: wontfix the issue is theoretically valid, but can't be accepted due to some kind of project limitations (e.g. development constraints, project scope, etc)
• type: question the issue is a general question to the development team (e.g. an RFC like the current issue)

Priorities

The following labels are quite explicit :-)

• priority: critical
• priority: high
• priority: medium
• priority: low

Spec

The following labels would tell which version(s) of the spec is affected by the issue:

• spec: all
• spec: EPUB 3.2
• spec: EPUB 3.0.1
• spec: EPUB 3.x
• spec: EPUB 2.x

Others

• newcomers friendly 🙂 indicates that the issue should be an "easy one", and a good place to start for a new contributor to the project

[rdeltour]

Thoughts?

[tofi86]

Great idea! 👍

I just added labels when I felt the need to have an additional new one but didn't stick to a specific system.

Overall: Good to go!

Small remarks:

• type: test -> type: tests
• type: chore -> kinda confusing at first sight. Any other idea?
• spec: at the moment we also have "feature" labels, like edupub. Do we want to keep that?

Do you also want to re-label all the old/closed issues?
When removing labels I think the label history in old issues is getting lost.

Do you plan to use a color code for the labels?

[rdeltour]

Overall: Good to go!

👍

Small remarks:

* `type: test` -> `type: tests`
* `type: chore` -> kinda confusing at first sight. Any other idea?

I admit I've taken this terminology from Angular's conventional commit guidlines, but we could certainly change it!

type:meta could be an alternative to type:chore, although I'm not sure it's much more explicit…

* `spec`: at the moment we also have "feature" labels, like  `edupub`. Do we want to keep that?

Yeah, I've been wondering that too. Maybe replace the spec category by a more general topic?

Do you also want to re-label all the old/closed issues?
When removing labels I think the label history in old issues is getting lost.

Good point, but I'm not sure keeping the history is necessary. When renaming current labels make sense, we can at least do that instead of removing+readding.

Do you plan to use a color code for the labels?

Not necessarily, except the classical "green-to-red" convention for priorities, and "red for bug" and "green for accepted". In any case, any color would of course be optional to the understanding, to respect WCAG 1.4.1 😊.
Did you have something in mind?

[TzviyaSiegman]

looks good, but depending on what management system is used, the "status" labels might be replaced by boxes or columns

[tofi86]

Did you have something in mind?

no, just asking.

When renaming current labels make sense, we can at least do that instead of removing+readding.

👍

Yeah, I've been wondering that too. Maybe replace the spec category by a more general topic?

👍

type:meta could be an alternative to type:chore, although I'm not sure it's much more explicit…

IMHO, meta still does not describe that very well: (the issue is related to a meta task like the build system, code generation, minor dependency updates, etc.)

How about type: other?

[mattgarrish]

How about type: other?

Would type: maintenance be slightly more specific, or is it a general catch-all category?

[rdeltour]

Would type: maintenance be slightly more specific, or is it a general catch-all category?

I like "maintenance", which reflects the original intent; and consequently no, it's not intended to be a catch-all type 😄

[danielweck]

I would prefer to stick to an existing standard practice, like Romain mentioned (conventional-changelog / standard-version / Angular vocabulary) https://github.com/conventional-changelog/standard-version#commit-message-convention-at-a-glance -- https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits
...so "chore" sounds okay to me :)

[rdeltour]

@danielweck I'm not sure if chore is really more standard, especially as "conventional commits" are really about commit message conventions (for automated changelog generation) rather than labels…

"maintenance" sounds probably more understandable by most people, but I'm fine either way.

[rdeltour]

The new labels are now in place.

If we want to revisit some of these, let's open new issues or discuss it during developers meetings.