[core-workflow] Tracker workflow proposal

[Ezio Melotti]

On Mon, Apr 21, 2014 at 11:42 PM, Zachary Ware
<zachary.ware+pydev at gmail.com> wrote:
> 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.
>

I think we are quite liberal in giving away the "Developer" role on the tracker.
The main issue that it might take a core dev notices that someone has
been actively contributing for a while and decide to check if they are
Developers or not.  If people request it on IRC they can generally get
it sooner.

>> 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.

Note that we shouldn't limited ourself to basic form elements.
In theory we could use any fancy js-powered widget (e.g. jqueryui, the
one I used for the nosy autocomplete), as long as it improves
usability and that the page is still usable when js is not available.
This is an example I found googling:
http://www.erichynds.com/examples/jquery-ui-multiselect-widget/demos/

>  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.

This can be done, but I would prefer a better approach where the exact
file names are extracted and normalized from each patch like I did for
http://wolfprojects.altervista.org/issues.html

>  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.
>

As I mentioned above, we aren't slow because we don't want to promote
people, but just because the promotion only happens when a core dev
happens to notice that someone deserving that role still doesn't have
it (and knows how to upgrade the role).  Maybe showing the role more
clearly (with an icon like the committer one) would make it easier to
notice when someone is not a Triager yet.

Best Regards,
Ezio Melotti

>> 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