Proposal: Create standard set of labels for Github issues

[aaronhirtenstein]

This issue follows a discussion in the Tech Group meeting on 7th July 2022.

Git issue trackers can be a little intimidating to non-developers who aren’t used to them and less experienced developers, so labelling can make them friendlier and more accessible. By having a disciplined system of labels - or even just using the GitHub defaults, it’s easier for community members to contribute to the project.

The proposal is to move to a standardised taxonomy of colour-coded labels, such as the following:

Skill level and orientation (greens)

• Good first issue
• Easy
• Moderate
• Difficult
• Question (or Research)

Contribution (pinks)

• Communications
• Design
• Dev
• Documentation
• Research
• Governance
• Accessibility

Technology / Development (blues)

• Bug (red)
• Backend
• Frontend
• Feature (or Enhancement)
• Technical debt

These lists are not exhaustive but we reckon these buckets will broadly help people understand quickly the types of issues they can get involved in. Some questions that arose during the meeting and that we need to resolve:

1. Should we prepend labels with the type (e.g skill level)?
2. what do we do about existing labels? Especially the story points ones
3. Do the 3 categories make sense? Is anything missing?
4. How do we implement this across all repos and issues queues?
5. How do we encourage people to use this? How / Where do we document this as a standard?
6. WHO will implement this?! 😄

This issue is intended to gather comments and suggestion from the community so we can form a policy and document it for future reference - and so we can implement the policy!

[msayoung]

Can we have Accessibility as a label in there please?

Could we append, rather that prepend the labels with skill level, if we think this is needed? It'll be easier to scan and less likely that the useful bit of the information will be cut off if the label is truncated.

[aaronhirtenstein]

@msayoung I've added Accessibility to the Contribution category, does that work for you?

And yes appending sounds sensible to me 👍

[aaronhirtenstein]

Assigned some people who were present at the tech governance meeting last week. apologies if this is not the right use of that function!

[finnlewis]

I think I need to review a few issues to understand how I would tag them using these labels.

In terms of categories:

"Skill level and orientation" makes sense across all issue queues. We could maybe do with an attempt at defining what we mean by 'Easy', 'Moderate' etc. Did these labels come from somewhere else that we might borrow definitions from? It is also probably hard to know how difficult an issue is to resolve at the start, apart from the super simple things.

"Technology / Development" makes sense across all issue queues. Again, perhaps a glossary of definitions would help define how we'll use them.

"Contribution" I'm not sure if that's quite the right word for the taxonomy, but not sure what would be a better word. Also not sure this would be applicable to all issue queues. Feels more appropriate for the main issue queue.

Prefixing:

I get it after looking at this: https://github.com/freeCodeCamp/freeCodeCamp/labels

labels like this now make sense to me:

scope: a11y scope: docs

tech: backend tech: frontend

status: wontfix status: in progress

[aaronhirtenstein]

Scope instead of contribution sounds good to me @finnlewis and prefixing looks useful.

One question I have when reviewing this issue queue is whether this is the right place for business issues e.g. https://github.com/localgovdrupal/localgov/issues/361 - could these be archived / closed / moved

I wonder also whether bug / enhancement / question are separate from the tech category - and don't need a prefix.

[aaronhirtenstein]

@markconroy @stephen-cox any thoughts on this?

[finnlewis]

Another thing just occurred to me @aaronhirtenstein

We have 'status' which maps to columns on the project boards:

So we probably don't need 'status' type labels.

And there is also 'Milestone' which could be used as some form of separation of issues based on target date / project / or even scope of work?

Looks like the due date is optional:

[markconroy]

Hi @aaronhirtenstein

I'm happy with what you are proposing. As I said on the tech group meeting, it's much better than what we currently have, so would be good to implement and then iterate further if we need to.

what do we do about existing labels? Especially the story points ones

DELETE THEM WITH FIRE. I see no value in them at all. And the inventor of scrum seems to agree with me:

Estimating tasks will slow you down. Don’t do it. We gave it up over 10 years ago.

https://www.quora.com/What-are-the-techniques-set-by-the-Scrum-guidelines-for-a-task-estimation-in-sprint-planning-Are-there-any-limitations-to-these-techniques/answer/Jeff-Sutherland-10

[aaronhirtenstein]

thanks @markconroy I'll revise the proposal to incorporate people's suggestions

re story points I think that is a proposal you'd need to bring to the dev team tbh. It would obviously simplify labelling for business as usual issues so I can see the benefit!

[aaronhirtenstein]

OK I've amended the proposal to bring in feedback from this thread in https://docs.google.com/document/d/1Y6eZTZfsXGTUXd2qplHTDmAZ-pt5AuOsOErIYqL39eA/edit#

I'm not really clear on the decision making process for this as it isn't code / a merge request so will ask that question on Thursday unless anyone has any ideas. All I can find is https://localgovdrupal.org/about-lgd/governance

[msayoung]

I've gone ahead and started adding the "accessibility" label to the repos that I come across so that we can see a list of all the accessibility issues here: https://github.com/issues?q=is%3Aopen+is%3Aissue+archived%3Afalse+label%3Aaccessibility+user%3Alocalgovdrupal

Lets revisit this at the next governance meeting ( on the 14th Dec )

[msayoung]

This seems related: https://github.com/localgovdrupal/localgov/issues/474

[msayoung]

We discuss this today in the Tech Governance Meeting.

We've passed the proposal for the bulk of the proposal apart from the colours.

The colours are hard to distinguish from one another, and having them so similar is possibly unnecessary if we are prepending the labels with the issue type.

We propose that we ensure that the following need to stand out from the rest:

• type: bug
• skill: good first issue

@aaronhirtenstein do you feel strongly about the types being the same colour theme?

Next steps

• Maria will revisit the colours
• Stephen will create the import script for existing repos
• Update the default issues on new repos
• Manually update all existing repos and issue queues

[aaronhirtenstein]

I don’t feel strongly about that and understand the rationale, glad to see a decision made and clear next steps, nice one! On 14 Dec 2022 at 16:53 +0000, Maria Young @.***>, wrote:

We discuss this today in the Tech Governance Meeting. We've passed the proposal for the bulk of the proposal apart from the colours. The colours are hard to distinguish from one another, and having them so similar is possibly unnecessary if we are prepending the labels with the issue type. We propose that we ensure that the following need to stand out from the rest: **- type: bug

• skill: good first issue**

@aaronhirtenstein do you feel strongly about the types being the same colour theme? Next steps

• Maria will revisit the colours • Stephen will create the import script for existing repos • Update the default issues on new repos • Manually update all existing repos and issue queues

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: @.***>

[msayoung]

I've started creating the labels to test on localgov_base https://github.com/localgovdrupal/localgov_base/labels

I realise we should also have descriptions. sigh...

[millnut]

@aaronhirtenstein I think one under "Technology / Development (blues)" for "Test" would be very useful

Edit: ignore after looking at the Google doc I see there is a tech: tests label

[jarvisryan]

This looks like something which may be helpful for us going forward now we have more and more issues being added. @carolinechristie1 @lfriedman1321 @japhetbonney @GavinSkull @kumarcjh

[finnlewis]

Note: be good to pick this up again, especially to help with pull requests