[core-workflow] Tracker workflow proposal

[Zachary Ware]

On Mon, Apr 21, 2014 at 11:04 AM, R. David Murray <rdmurray at bitdance.com> wrote:
>
> OK, wall of text time.  Sorry about this :)

You weren't kidding :P

> Tracker Roles
> ~~~~~~~~~~~~~
>
> The tracker roles important to the workflow are:
>
>     User
>     Triager ('Developer')
>     Committer
>
> Although the tracker calls the Triager role 'Developer', I'm going
> to refer to it as Triager throughout this document, for clarity as to
> its intent.
>
> The tracker does not currently have a role equivalent to 'committer', but
> we may not need to add one explicitly, since the account of a committer
> is marked as such.
>
> The important thing to understand about these roles in the context of
> this document is that anything a user can do, a triager or committer
> can do, and anything a triager can do, a committer can do.

I think it may be worthwhile to actually implement these roles as
named, and promote people to Triager a lot earlier in their Python
career than we currently promote to committer.  I think it would be
worthwhile and help with retention to "reward" (with more work) people
who have made a couple of non-trivial contributions and seem
interested in doing more; people like, for example, Vajrasky Kok,
Nikolaus Rath, and Todd Rovito who if I'm not mistaken only have the
User role currently.

> Versions
> ~~~~~~~~
>
> Currently our versions field does double duty: we set it to the versions
> we want to fix the bug in, and then deselect versions as we fix them.
> However, I noticed when doing the "What's New" document that this
> makes things really confusing if you *do* look at the ticket later.
> You can't tell which versions got the fix without reading through the
> entire issue.  So I'd like to split this into two fields:
>
>     should be fixed in: [list of versions]
>     has been fixed in: [list of versions]
>
> I'd also like patch set links to be displayed next to the versions for
> 'has been fixed'.  When a commit references an issue, it should appear
> next to the appropriate version, but it should *not* automatically
> change the version state to fixed.  That should require separate action,
> since we sometimes apply patches that are relevant to the issue but
> do not fix it.  When an issue is transitioned to closed, there should
> be an easy way to say "mark all versions with changesets as fixed".
> It would probably be appropriate for that to be the default.
>
> These fields have direct operational meaning: they indicate a task
> to be performed or signal the completion of a task.

As may become apparent as this message goes on, I'm a fan of
checkboxes.  I don't much like the current method for selecting
multiple versions or components, which requires both keyboard and
mouse to make the selections in most cases.  Since it's not an
extremely common form element on the modern web, some users (not
necessarily just Users) may not even be familiar with how to pick and
choose specific ones--I suspect this may be part of why we have so
many issues created with every version selected, the user attempted to
choose 2.7 and 3.current but didn't know how to only select the two.
So, my suggestion here (also colored by Barry's thoughts on release
blocking) is to have a series of checkboxes for each version,
"affected", "blocks release", and "fixed".  Or even just "affected"
and "fixed", with a priority box per version.

> Type
> ~~~~
>     documentation
>     python bug
>     interpreter crash
>     security
>     enhancement request
>
> I add 'documentation' here based on PyCon feedback from Jessica McKeller
> and Selena Deckelmann.  None of the existing types makes sense to a
> beginner for a documentation bug, and the resulting confusion can lead
> someone to abandon the effort to contribute.  It also has operational
> implications (see below).
>
> I rename 'behavior' to 'python bug' for a similar reason, but I don't
> have any usability data to back that feeling, so I'm not strongly
> advocating that change.
>
> I rename 'crash' to 'interpreter crash' in an attempt to reduce the
> chances that someone will report a python traceback as a crash, something
> that otherwise happens very regularly.  I'm sure we'll never completely
> eliminate those.

Perhaps it could be made even clearer by naming them "python bug or
traceback" and "interpreter crash (segfault)", or even just calling
"interpreter crash" "segfault/abort".

> I drop 'compiler error', 'resource usage' and 'performance'.  All of
> these are bugs in the minds of the reporters, and classifying them
> separately in the 'type' field does not, as far as I can see, lead to
> any operational difference in the way the issue is treated.

I think it would be good to keep these as "components", as Antoine suggested.

> Component
> ~~~~~~~~~
>
> I propose that we completely change the nature of this item.  I think we
> should make it a text field that is filled in by autocomplete like the
> nosy field can be, and that the value be any of the components listed
> in the experts file.  This would further respect how the experts have
> listed themselves in that file by autonosying those that are willing
> for that to happen.  The field should still be a multilink (that is,
> can contain more than one value).
>
> This change would mean that it would be possible to search for issues
> based on module, which is an often-requested feature.

I like this idea quite a bit, especially changing the type of input widget.

> Patch Status
> ~~~~~~~~~~~~
>
> This is a new set of fields that records information about the patch:
>
>     unit test
>     fix
>     documentation changes
>     news entry
>     what's new entry
>     commit message
>
> For each of these, the value could be 'needs work', 'complete', or
> 'not applicable'.  For issues of type 'documentation', all lines
> except 'documentation changes' and 'commit message' would be set to
> NA by default, otherwise they will be set to 'needs work' initially,
> except for "what's new", which will be set to NA for anything except
> type enhancement.

Instead of having 3 textual options for each field, I'd prefer
checkboxes (or perhaps a series of checkboxes).  For each field, have
three checkboxes, "needed", "present" and "ready".  "needed" would be
visible only to Triager+; unchecked fields are not needed for a
complete patch and that field is hidden entirely from Users.  In the
majority of cases, "present" could be set by sniffing through a patch
when it is attached; if a patch contains "^diff.+Lib/.*test.*\.py$",
chances are very good that it has a unit test.  The "present" checkbox
should probably just be a graphic for Users, but available to Triager+
to clean things up where automation fails.  "ready" would be checked
by a reviewer who approves that particular part of a patch.

> Keywords
> ~~~~~~~~
<snip>
> I think the keywords should be settable by anyone, if they aren't already.

They're not, unless it's changed since November.

> Issue States and State Transitions
> ----------------------------------
>
> Here are the states that I think an issue can be in:
>
>     new
>     needs information
>     needs decision
>     needs decision from committer
>     needs patch
>     needs review
>     needs patch update
>     needs commit review
>     closed/fixed
>     closed/wont fix
>     closed/duplicate
>     closed/insufficient information
>     closed/postponed
>     closed/not a bug
>     closed/third party
>
> I discuss each of these, and the possible state transitions, below.
>
> All legal state transitions should be displayed in a particular
> area in the UI, and each transition should be a single radio button.
> Which possible transitions will be displayed will depend on the user's
> roundup role, and occasionally other state in the issue.
>
> The default transition is "no change".
>
> Note that the names of these states are, unlike most of the other names
> I've used so far, not the ones I necessarily expect us to use in the UI.
> They are descriptive of the state from the workflow POV, not necessarily
> the labels that should be used for the state *transitions*.

I like this scheme, and I think the split of abilities between roles
is reasonable, as long as we promote people to Triager a lot faster
than we currently do.

> Dashboard
> ---------
<snip>

I like this too, it's a vastly superior extension to a few saved
queries that I use.

> Big Picture
> -----------
<snip>
> That's my intent, anyway.  You tell me if you think I'm headed in the
> right direction.

Looks like a good general direction to me.

-- 
Zach