Determine and document process of working on issues

[mattstratton]

Up until now, the only contributor to this project was @mattstratton , so the process didn't matter much. Given that we have other folks who want to work on this, having a lightweight (please!) way to determine priority of issues and what should be worked on would be really helpful.

Let's use this issue to talk through how this might work, and once it's decided and documented, we can mark this issue as done!

[mattstratton]

I have ZenHub set up on this project for things like epics, backlog management, etc. I plan to keep using this, and would be happy to give access to anyone who needs it (I think I need an email address to invite you; I don't think I can invite just by GH user - if you want an invite, DM me on Slack with the email address).

The upside of Zenhub is that it's a lot easier to order things in priority, etc. Of course, you only see this ordering if you're viewing Zenhub; the issues in GH still are ordered by other methods.

My general thought is that we use the following buckets for issues:

• New Issues: These are issues created that have not been reviewed yet
• Icebox: These are "yeah, we don't want to close this issue yet, and it's not a wontfix, but we likely are not going to do anything with this in the foreseeable future"
• Backlog: Issues that are not ready to be worked on just yet, but we want to work on them soon, or soon-ish.
• Ready: Issues that have been prioritized and ready for a contributor to tak on.
• In Progress: Someone is actively working on this issue
• Review: Mostly I think this means there is a PR for this issue; basically means a PR has been submitted and it is ready for code review/testing
• Done: yay!

These buckets will also have an associated GH label with them, so even if you don't use Zenhub, you can, for example, filter to find issues with the tag of "Status: Ready" and find something to work on, etc.

[richardboydii]

@mattstratton does ZenHub respect / replicate tags from GH issues? The reason I ask is that with the above proposal we'll have three buckets of issues that aren't ready for work, with four total being categorized as "not working on yet". Could we use a "groomed" tag to denote the state of an issue and slim up our work buckets?

• Icebox - Not an active work priority.
• Backlog - Items that we want to work on. New issues fall here as well.
• Frontlog - Items that are groomed and prioritized.
• In Progress - Someone is actively working this.
• Review - Need another set of eyes to validate.
• Done - Shipped.

These columns would be supplemented by the following tags:

• Groomed - If an issues has been groomed it gets a tag. Otherwise we know it hasn't been groomed because it lacks a tag.
• Blocked - Anything that has an external dependency (other issues, upstream library breaking change) gets this tag, so that we know we can't get the ball over the line yet.

[mattstratton]

Labels

There are a lot of various labels in this repo, which illustrates that I've messed around with different ways of categorizing the issues. Here's the ones that I think we will keep and what they mean:

Status Labels
These all start with Status: and are used to designate what's going on with the issue. Examples are:

• Status: Icebox: as mentioned above, we aren't ready to even think about this yet, but we don't want to close the issue
• Status: Accepted: this issue has been reviewed by @mattstratton and it is in the backlog
• Status: Ready: this issue is ready for someone to work on it, so a contributor can grab it!
• Status: In Progress: someone is actively working on this issue

Type Labels
These all start with Type: and are used to categorize the content/subject area of the issue. Examples are:

• Type: Bug: Something's broken - an existing feature is not working as expected
• Type: Enhancement: A feature request, or a way to make something better, but not fixing broken things
• Type: Documentation: Writing a doc, updating help files, etc
• Type: Question: This is a special kind of issue that is more around discussion than any actual code changes. Examples might be "should we rewrite this whole thing in node?" Or maybe something not quite so big and controversial, so more realistically, "should we change the pipeline from Travis to Circle?"

A couple other labels that will probably stick around:

• good-first-issue: following the suggestions at https://github.com/github/opensource.guide/issues/1052, this will label issues that are good choices for someone new to the project to tackle (note: this issue label does not currently exist in this project)
• quick-win: Small fixes that shouldn't take a lot of effort to knock out. An optional label but maybe helpful.
• wontfix: issues that we are not going to do anything about; good practice to label these prior to closing
• duplicate: similar to wontfix; this is just a management label.

[mattstratton]

@richardboydii turns out that zenhub doesn't update GH labels based upon the bucket they are in, but as the backlog manager I can manually do this when I move them around (it's not a big deal).

"Frontlog" is basically what I was calling "Ready".

"New issues" is basically an unlabeled issue and it is a zenhub bucket; the idea there is that those are issues that need intial grooming as in "do we even want them in the backlog, period". Nothing should live in "new issues" for very long; it will be a quick "is this a clear wontfix or duplicate, and if not, punt it into the backlog.

Things get pushed into icebox after having been in backlog for too long, imho.

So the general flow of an issue would be like this (maintainer right now is just "Matt", but we can add more owners later):

1. Issue is submitted
2. Maintainer reviews issue to see if it should be considered. If so, it's pushed into backlog.
3. Maintainer regularly grooms the backlog for priority. Items that are old and not happening any time soon are moved into icebox. Maintainer orders the backlog items in order of priority. Issues at the top of the backlog that should be worked on are move to "Ready"
4. A contributor looks for issues with the "Ready" and assigns the issue to themselves and moves them to "in progress" (if the contributor doesn't have zenhub access, they can just assign it to themselves and the maintainer will update the zenhub stuff and label; it's not a huge thing to worry about I guess?)

and so on...

[mattstratton]

There's an ability in zenhub to mark an issue as dependent on another issue, and that will be reflected in github somehow too IIRC

[mattstratton]

Here's what a blocked issue looks like in zenhub:

This is what it looks like in github with the zenhub chrome extension:

If you don't have the extension, you don't see anything related to the blocking in github :/