Issue Review Examples

During discussions between Max, Craig, & JD we thought it would be helpful for us and the broader team to review some of the longstanding github issues to see if we could break them down a bit and translate some actionable items.

I thought it would be useful to use a couple issues as example cases of how we might've altered them in retrospect. General goals are:

• identify tasks that are too broad/undefined/'stuck'
• if the task is really a discussion, label it as such to indicate there may not be clear 'completion' criteria
• otherwise, break down these tasks into action items with clear target outputs

https://github.com/terraref/computing-pipeline/issues/46 search clowder for data
Here's an example issue that was created last January. The general goal of the issue is stated:

Should have a complex query capability to find data in clowder. This should allow the user to do complex queries like find all data that has LAI > 10 AND is type XYZ.

...however, this is still a difficult issue to close. There's no specific requirements, only "do complex queries like..." with two examples (plus another from Jeff). Even if those were specific requirements, this essentially covers several months of work in a single sentence without any de facto milestones to make tracking progress easier. I suggest in the comments that my search pull request addresses this issue, but in reality that PR is V1 and we have additional search features covered under this scope (e.g. search by location) that could really be in some V2 issue of search improvements.

So if we were to create this one again, I might suggest a sequence more like (idea being that we create the next sub-task issue when the previous is done):

Issue 1: Discuss initial search requirements with David, JeffW, whoever else
Completion criteria: Have a meeting, potentially share meeting notes somewhere

Issue 2: Max creates design document with target set of initial features
Completion criteria: Wiki page that says Search V1 will support X, Y, Z

Issue 3: Development of features
Completion criteria: One or more pull requests addressing those features & review

Issue 4: Deployment to TERRA test/production instances
Completion criteria: New search code is deployed & ready

Instead of 4 individual issues we could also have one issue with these entries as 4 checkboxes, but Craig made a fair point that there's something to be said for having more manageable "week-sized issues" instead of "several month issues" so we can close things more regularly. Another hope is that more tangible action items for these long-lived efforts will make prioritization easier, because we don't have to prioritize between e.g. 3 issues that each represent several weeks of effort and instead prioritize between 3 stepping stones of those issues that represent a day or two's worth.

Of course, there is a point where the tasks get too small and you spend more time updating github than you do actually doing the tasks - we don't want that either :)

As a first step down this path, we're going to label some issues with the 'massive' label I just made to mark them for review and possible breakdown into new smaller tasks.

Rob also suggests looking into Projects in GitHub (I see CyberGIS has one, for example) as a way to manage long-running large tasks into smaller chunks.