Standardize our git 'types' used in issues types and issue labels, branches, and PRs

[qredwoods]

Context

why does this issue exist? if we're solving a problem, describe the frustrating/problematic experience. If we want something new, describe the general motivation for the feature

Here are examples of what I mean by types: chore, bug, bugfix, task, documentation,feature, new feature, enhancement,data science task, default - a different subset of each is used across 5 different menus one encounters on the journey from
Issue creation --> issue labeling --> branch creation --> pr.

Which type do I choose, uh oh that doesn't exist in the next step, or sometimes I can select multiple, should I? are examples of the ambiguity and slowdown created by this situation.

• Issue creation. On clicking New Issue, one is presented with 5 template options

Bug and Feature probably have the least ambiguous paths in the current system, so let's look at the case where it's a task that is neither of those.

On selecting Default template: the auto-population title is [NEW DEFAULT TASK] ok one might gather, this is a task. Once the issue is created, one might go to issue type, and see these types.

"Ok, task is an option let me select that."

Then one might think to check labels, which use to indicate which team it pertains to, and if something is a good first issue. Ah, there is a bug tag! I wonder if there is a task tag."

Oh hmm, chore is the only result, I guess I will choose that?

Then someone comes along to create a branch. They follow the convention of using a Type/Category as the first thing in their branch name. The example dev here has a choice... do they branch as task/9999/example-issue or chore/9999/example-issue. Ok let's say they choose 'task' as in issue creation they've seen 2 indicators in favor of task and only one in favor of chore. Ok task/9999/example-issue is created. The dev happens to glance at other branches and see a lot of branches that start with chore and a few that start with task - "Did I choose correctly, maybe there's some convention I don't know" and "maybe it doesn't matter? maybe it does?" They stick to 'task'.

Then its time for a PR.

In the template we have -

(Note that data science task has no option here, should it? It has a GH issue template for it, though it has no tag, though there is a data science tag? maybe data science + chore = data science task?)

Encountering the PR template, example dev now realizes that choosing task as the type and task/ as the branch title was either wrong, because there's no task option after all, or guesses that chore on the PR template is synonymous with task as an issue type. So task is passable but still maybe I should've just chosen chore earlier on, but hm, there was no chore type, only a chore label. does that mean types are meaningless, and only labels matter?

Such are the ambiguities.

The different categorical labels at each stage:

Issue Template: default, bug report: create a report to help us improve data science task template: scopes out analytics, data engineering, tasks, default template: general purpose issue template, feature request: suggest an idea for this project, blank issue: create a new issue from scratch

Issue types: bug, an unexpected problem or behavior, feature: a request, new idea, or functionality, task: a specific piece of work

Issue labels: bug: something isn't working, chore: technical task or maintenance, documentation: improvements or additions to documentation, enhancement

PR types: bugfix, chore, new feature

---

Will try to add a comment of a drawing of these different concepts and how they weave together.

Definition of Done

what tangible outcomes define this as issue as complete

Foster discussion among interested parties and implement the best approach.

Proposal Part A.
I propose we have these three categories
bug
feature
chore - this should be the truly catch all
and come to consensus on a single definition for each that is used across all areas, and replace all semi-dupes with them (task for chore, enhancement for feature)
Proposal Part B.
I propose we make documentation a first class type, like bug and feature, and come up with a clear abbreviation... doc, or the verb/noun document, or perhaps docs as it is a contribution to docs, or the unapologetically lengthy documentation

I don't think we should have more than 4 Types.

Part C.
Things that need decisions which I haven't formed an opinion on

1. bug in issue and type becomes bugfix in branch convention and pr. I see some repos call it patch I'm not sure if it makes sense to try to enforce bug vs bugfix. arguably it should be bugfix throughout because it is a request for someone to fix a bug. I don't know, either way could be simplified, but not our main issue because at least everyone knows it pertains to a bug
2. To Type types, or To Label types

I've only addressed github types, and not labels, in my approach

Since type has a nice separate display alongside issues, I think it's worth using it. And we can remove / deprecate / migrate / phase out, past labels of chore, bug, enhancement, and leave labels to other functions like team specificity and good first issue. (There could be another ticket to clean up all the non-type labels separate from this.)

But another option would be to empty out the type category, and just set as labels all of these things. This I think risks that people won't Type their issues, because it's easy to forget Type labels when Labels is already doing so much, versus just having in README under Git Workflow - Issue Creation -- please choose a Type when you create an issue -- here's what they are, etc.

COMPLETION:

Once discussion concludes, go and amend accordingly

• issue templates
• issue Types
• issue Labels
• Git Workflow in README re branching conventions
• PR Template
• any other relevant definitions and clarifications into the README

Engineering Details

what sort of details are needed for someone to pickup this issue? Are there any specific files or areas of the code that they should reference?
Issue #736 includes details on the branching convention @agennadi taught me, but it's basically type/#/title - looking back most tend to at least do type/title, though there are many likely older branches that follow no convention.

I see bugfix is pretty common branch name convention out there. Even more common is the distinct hotfix/ for out-of-cycle urgent changes to go quickly to production.

For a contrasting view, here is an aws suggestion on how to name / structure branches.

For reflecting on this I read some google results on the topic of chore, and stumbled on the debate about Conventional Commits, which proposes many more categories (8) and much stricter structure and I see others saying that's too detailed and unnecessary. I tend to agree. You can have fun reading about it here but not necessary. Note this is about the commits level but I think it flows up to Types.

People discussing the pro con of 'chore' and by extension Conventional Commits

14 year long discussion of Chore on Stack Overflow, ruled as Subjective

Cheatsheet of how Conv. Commits describes different commit-level Types - this is an example of the 8 or 9 is too many thing I refer to above.
Same list of types on someone's blog but with fun emojis

Again I think that we pick and adapt the 3-4 that make the most sense for our team, and everything I read says it ultimately needs to be specified at the org/team-level, not some external standard. I value our collective sensibility, experience, and wisdom.

Thanks for your patience with me going comprehensive here as I'm new to this topic.

[qredwoods]

Heard from Anna @nickvisut had been discussing similar themes to this.