Sort out GitHub issues for gitbox repos

[wohali]

We've got 'em, we want to use 'em instead of JIRA. Everyone on the project is +1, we just need a system. Here's some proposed rules; I'm keeping them simple.

Assignees

Self-explanatory.

• Assign yourself if you start working on an issue.
• De-assign yourself if you abandon an issue or won't be able to address it promptly.
• Don't assign an issue to someone else without their explicit approval.
• To avoid cookie-licking, our PMC should consider periodically de-assigning idle issues. How idle is idle? 3 months seems a good timeline to me. Writing a script to do this that runs on a cronjob should be straightforward.

Tagging

I particularly like what Robin have done with their colouring-and-categorizing system. So, inspired by that, here's the proposal. Remember an issue can (and probably should) have more than one tag.

• Component: Various sub-components of Apache CouchDB. Can be expanded with search, geo, etc. in the future. (light blue)
  • build (toolchain, CI, etc.)
  • documentation (and/or below in Experience?)
  • dbcore (CouchDB database core)
  • fauxton
  • http_api
  • javascript
  • mango
  • nano (couchdb-nano client)
  • packaging (.deb, .rpm, snap, etc.)
  • plugins
  • replication (debatable, but this comes up enough)
  • testsuite
  • viewserver (the API)
• Problems (red) - Issues that make the product feel broken. High priority, especially if its present in production.
  • bug
  • security
  • production
• Mindless (beige) - Reorganizing folder structure, legal stuff, and other necessary (but less impactful) tasks.
  • chore
  • legal
• Experience (orange) - Affect user’s comprehension, or overall enjoyment of the product. These can be both opportunities and “UX bugs”.
  • UX (could include API debates or installation as well as Fauxton)
  • documentation (and/or above in Components?)
  • design (primarily for Fauxton)
  • website (https://couchdb.apache.org/ and related websites)
• Environment (pink)
  • windows
  • linux
  • macos
  • freebsd
  • docker
  • etc.
• Feedback (magenta) - Requires further conversation to figure out the action steps. Most feature ideas start here.
  • discussion
  • rfc
  • question
• Improvements (blue) - Iterations on existing features or infrastructure. Generally these update speed, or improve the quality of results.
  • enhancement
  • optimization
• Additions (green) - Brand new functionality.
  • feature
• Pending (yellow) - Taking action, but need a few things to happen first. A feature that needs dependencies merged, or a bug that needs further data.
  • in progress
  • watchlist
  • waiting on user
• Inactive (grey) - No action needed or possible. The issue is either fixed, addressed better by other issues, or just out of scope.
  • invalid
  • wontfix
  • duplicate
  • on hold

Projects

Not useful for us right now.

Milestones

We should be using this for version targeting and mass-updating as necessarily. I.e., bugs get targeted for the next minor release, new features that break the API for the next major release, etc. Think v2.1.0, v3.0.0, etc. (Rathole: v or no v?)

Issue template

Going to start with this one.

PR template

Update to change reference from JIRA to GH Issues. Remind people to include text like "Fixes #472" to link a PR to an issue.

Contributing

We've had requests for this before, should we add one?

Multi-repo

We still have a number of repos that aren't likely to be merged into apache/couchdb, like fauxton. I am suggesting we keep primary issue reporting here (in apache/couchdb) for all of our repos, and reference issues here from PRs in other repos (via #472). We shouldn't disallow issues in other repos, but my guess is that they'll be limited to people 'in the know.'

[wohali]

I have gone through and tagged all the open PRs against apache/couchdb as a test of the labelling system. It seems to make sense to me.

[sagelywizard]

I'm generally +1 to everything here. I'd say we should add a CONTRIBUTING.md file. Also, I'm a bit confused how we'd use milestones. Would we have a "next minor release" milestone and add all minor-release-type issues to that milestone? And then move those to the specific "release 2.1.6" milestone when the code ends up in master?

[wohali]

Yes, I think you've got exactly the right thing for "next minor release," except that we'd simply edit the label to become "2.2.0" once we knew what the numbering might be. (major.minor.patch right?) Alternately we can simply start with defining 2.1.0, 2.2.0, 3.0.0 etc and just assign things as necessary, and move them out to another milestone (or to no milestone if we can't make a commitment).

[sagelywizard]

Would it make more sense to use tags for that? I'm not super familiar with the release process, but it seems like we'd want "next major/minor/patch release" tags so the release-maker-person would know which issues are going into the next release (and then the tags could be changed to the release name). Milestones might be nice if we decide that certain issues are going to block a release from being pushed. Does that still happen post-2.0? I'm not sold on anything, just thinking.

[wohali]

The point of GitHub's milestones is to associate a milestone name, description, and optional due date with one or more issues. Milestones can also be open or closed. Typically I see milestones showing what work remains to get a release out the door - you get a nice little bargraph in the UI, for instance. But milestones could also be feature related.

Tags don't give you the bar graph or due date, and the tag space can get cluttered quickly (we already have 30 tags to choose from.) I'm nominally against using tags to coordinate releases as a result.

If we mirror what we've done in the past in JIRA, there are 2 scenarios where we've used the "Fixed in release" field that would match the GH Milestone function:

1. To show we've fixed a reported bug and that it'll be patched in the next release
2. To put a stake in the ground to say an issue is a release blocker
3. Generating release notes

In that way I'm in favour of porting over exactly those 3 scenarios from JIRA "Fixed in Release" to GH Milestones.

[wohali]

OK, labels are live on this repo. I have only normalized the pre-existing labels on the other top-level repos and not implemented the full scheme on them. Fauxton also had a few of their own labels that mostly match this system, but I'd encourage @garrensmith @michellephung @robertkowalski to complete the process in the future if desired.

Thanks to everyone (including the CouchDB PMC) for the feedback!