Document how we work with GitHub labels

[honzajavorek]

• in progress is meant for PRs which are open, but should not be reviewed yet nor merged
• Except for in progress we usually do not attach any labels to PRs
• bug is meant for issues about bugs
• flaky test is meant for issues about flaky tests, the severity is equal to bug
• low hanging fruit ...

etc. should go to contributing docs.

[kylef]

I'd like to sync on this so we can have consistency across our OSS in ADT too.

[honzajavorek]

Except for what I described above there's:

• behavior change, which should probably mark breaking changes, but I don't presonally use it much.
• I use duplicate to mark duplicate issues before closing them, so if someone finds them, they can immediately see it's closed because there's equivalent issue, not because it's fixed.
• There's security issue, which I used to mark vulnerabilities. Should be probably named vulnerability instead, to be consistent with terms used by Snyk.
• I'm not sure how much improvement label is useful, because basically anything else then bug is improvement or discussion/question.
• I don't mark discussion/question, I just try to answer and close the issue ASAP if the OP is satisfied with the outcome or when they won't come back.
• low hanging fruit is something we use for issues we identified with @netmilk as small tasks anyone can easily come and do. I think they could work as good tasks for first time contribution or as something maintainers choose to work on when they're out of stories in the sprint. Or when they're bored in train.
• I thought of a label which would indicate I'm willing to coach someone to deliver an issue. But I'm willing to coach anyone on any issues, so this is probably equivalent to the one above.
• There are Epic: something labels in golden color (I was corrected by @netmilk it's gold, not dirty yellow). Dredd has several big areas which need significant attention and which are root causes for many issues. We call them epics and treat them as epics in our sprints. Some are just tidying up (make sure we work correctly with URI parameters), some are product development (rethinking of transaction names).
• There are Context: something labels, which help us identify issues related to a specific dependency, operating system, API description format, etc. Those are useful for basic orientation in context of the issues and ideally, ADT could actually watch issues having certain contexts. But there's not so many of such issues at the moment, so I'm okay with mentioning you explicitly. Looking at current context labels I personally think JS hooks should be actually an epic.

BTW I don't keep the same labels elsewhere then in the Dredd repo, which is maybe a shame...

[honzajavorek]

Note: mention in docs we're using specific colors for expressing the context (red = bug) or colors from this palette.

[kettanaito]

If the documentation allows, I suggest to fetch labels using GitHub API and use their description to compose some sort of table in the docs that would guide contributors regarding each label's purpose. Maintaining two lists of labels in GitHub and docs would be tedious. Of course, some meta explanations (like color schematics) can reside in docs explicitly.

[honzajavorek]

That's a good idea, we have Sphinx extensions to do that: https://github.com/apiaryio/dredd/tree/master/docs/_extensions If anyone is interested in helping with that, I recommend seeing this talk first.

[honzajavorek]

Also, this gets more importance once we move the smaller projects under Dredd as a monorepo.