[Development] Proposal: more Jira states to track stages of the work on an issue

[Edward Welbourne]

TL;DR: I struggle to find any substance in André's objections.
Meanwhile, I'd really like to hear from folk more familiar with Jira:

* Would a new state actually make it possible to show a useful
  distinction, on Jira's scrum boards, between tasks in progress and
  those in review ?  Or is Jira's scrum board too tied to "In Progress"
  for a new state to be any help at all ?
* If that *is* viable, would a tag suffice to achieve the same effect ?

A clear answer from a Jira expert on either of those would be more
interesting than the present discussion.  There are other uses for the
"In Review" distinction, but my current purpose in proposing it is as a
way to make Jira's scrum boards more useful.

On Wed, Feb 19, 2020 at 09:45:48AM +0000, Edward Welbourne wrote:
>> I very much doubt the distinction between In Progress and In Review is
>> going to involve much bike-shedding.

André Pönitz (19 February 2020 22:34)
> *shrug*
>
> Assuming that JIRA states are meant to be disjoint and that the names
> actually bear some meaning, "In Review" would mean "Not in Progress".

That's silly.  Does "In Progress" mean "No longer Accepted" ?
Does "Accepted" means "No longer Reported" ?
I doubt anyone is so silly as to read it that way.
Nor would any read "In Review" as "Not in Progress".

> Which already would be an interesting message to the reviewer. Like,
> "whatever you do here, that's not considered 'Progress'".
>
> Of course, nobody intents to bui^H^H^Hsend such message, and that's
> easily solvable, by either dropping the connection between state names
> and meaning, or by dopping the disjointness of states.
>
> What do you prefer?

That folk not wilfully misinterpret state names for the sake of vacuous
rhetorical grand-standing.

>>>> Already now there are tasks that get prioritized, and assigned, and
>>>> re-prioritized, re-assigned, "Fix-for-version"-ed, closed, re-opened
>>>> several times. Watchers that e.g. wait for a "Done" there get notified
>>>> each time on such unprogressing transitions, and skipping these sums
>>>> up to quite a bit of unproductive time already now.
>>>
>>> True enough; this would introduce one more transition, so one more
>>> e-mail per bug.  None the less, it's a transition that does mean
>>> something useful to those watching - especially those waiting for a fix
>>> - we are a significant step closer to a fix,

> Is is?
>
> First, being on review might still not mean getting closer to 'Done'.
> Patches get rejected or delayed for real or imagined reasons, nobody
> might actually review, a successful review might not be convincing
> enough for CI to let it pass etc, etc.

The fact that sometimes we think we've fixed a bug but later have to
re-open it doesn't persuade anyone - unless perhaps you - that we
shouldn't have a Closed state.  Likewise, the fact that sometimes we do
a bunch of work in an attempt to fix something, but it all come to
nothing, doesn't mean it's useless to have the In Progress state - even
if the progress we thought we were making proved vain, it was meaningful
to say we were trying to solve the problem.  In the same way, when we
think we've solved the problem, it's meaningful to make that clear, even
if we haven't yet got past review and integration, which might throw us
back to having to hack on the code some more.

> Second, water-level reports on how close something is to being done
> is practically never the reason why I watch tasks, I watch them
> because I may need to act once it is resolved. And only then.

Jira does not exist only for you, or indeed only for developers.
It facilitates communication between all stakeholders.
It serves purposes for some stakeholders that are of no value to others;
and the resulting e-mails that matter to some are thus a cost to those
who don't find those messages interesting.  What matters is whether, on
balance, it provides a net benefit.

>>> and there's a patch they might even be interested in applying
>>> locally.  And, as Lorn pointed out, issues don't have to go through
>>> every stage; it'd just be there for the benefit of those who find it
>>> useful.

> And to the distraction to those that don't. That's why the 'Verified'
> state was removed not that long ago.

Presumably we concluded that the benefit of the state didn't outweigh
the cost.  The reason I've started this discussion is that I believe an
In Review state would outweigh its cost.  You clearly disagree, although
the reasons you give for disagreeing don't sound at all persuasive to
me; they sound more like wilful curmudgeonliness, thus far: raising
objections that would apply just as robustly to the basic "Reported ->
Fixed" work-flow that a minimal bug-tracker would have.  Is a Fixed bug
no longer Reported ?  Of course not, it's both Reported and Fixed.  Is
it pointless to have a Fixed state just because sometimes we re-open
bugs ?  Of course not, it's better to claim it's fixed when we think it
is, and admit our error when it turns out we were wrong, than to not
give any indication of the fact that we *do* think it's fixed.

>>> Yes, we could do that with a tag, although I'm not sure how well
>>> Jira's "scrum board" view would integrate with that.  In any case,
>>> adding such tags would generate mail, just as state transitions
>>> would, and cluttering Jira with a plethora of person-specific and
>>> team-specific tags

> We have "Reported_by_X", "Y_thinks_this_is_a_P1", "up",
> "Earmarked_by_Z", and a lot more. And it's completely fine to have
> them. The rule to handle them is easy: "If you are not fully convinced
> it is meant for you it /is/ not meant for you".

And that's what I'll use if I can't get what I think would work better;
but it has the fundamental problem that it's unsystematic.  The
transition to review is usually meaningful when we fix an issue in Jira
and Jira has interfaces like scrum boards that I suppose can be taught
to use a common state, but that would need every single user to
configure individually if we use tags.

>>> might not be the clearest way to communicate with folk; in
>>> particular it'd mean there's no uniform way for teams to communicate
>>> this, making it harder to write tools that can be shared between teams
>>> with similar work-flows.

> Can't comment here, as I don't know what kind of tools this refers to.

The tools I'm thinking of are the scrum-related tools that our team is
using to co-ordinate our work.  I will confess that I'm no Jira expert,
so one meaningful objection would be "Jira can't do that", if someone
who knows Jira better can tell me this - but I'm hoping we can adapt our
standard views of where tasks are in our work-flow to make use of this
distinction.  So one of the things I *do* want to know, before we go
ahead with my suggestion, is whether Jira can actually use it in the
ways we need.

>>>> Looks like we are getting to the actual problem here. It's not
>>>> about development after all.
>>>
>>> No "getting to" about it - my original mail was quite explicit about
>>> the point of the exercise being clarity of communication with my
>>> scrum master (whose beard is plaited - I would not call his hair
>>> pointy).

> I am positive an "Eddy-calls-this-Done" label will be explicit enough
> to communicate the fact that Eddy calls this "Done" within this
> particular relation.

Yup, and Timur-calls-it-Done, and each and every member of the team's
own tag, but that's unlikely to make life easier for the consumer of
this information, so we'd probably end up with Foundation-Done or some
similar tag, which is clear enough to those who need to know it; but I
don't know how well it integrates with Jira's other tooling.  If it's
just as easy to adapt Jira's scrum boards to use such a tag as it is to
adapt it to use a new state (this condition includes the case where the
latter is impossible, of course) then I'll lose interest in having a new
state.  You'll still get spammed with e-mails when we make this
transition, though; it'll just be an "added a tag" rather than a
"changed state" e-mail.  Is it easier for you to filter out one of those
kinds of mail than the other ?

>>> We've had tasks where the actual coding was done in one sprint but
>>> the review and integration (and waiting for merges up from one
>>> branch to another) have happened in other sprints. Distinguishing
>>> those parts of the work would make sprint organisation easier.

> Ok, more seriously: I think you want to communicate "I did what I can
> do here, for this period of time". This is a valid, and noteworthy
> state, but at the same time orthogonal to the existing JIRA states. It
> would also apply to an "Won't do", or "Invalid", or whatever else
> state you chose after working on the issue. This calls for some markup
> that is orthogonal to existing JIRA states, and a label provides that.

I don't see why it's orthogonal, unless you in fact consider "In
Progress" to be orthogonal.  It draws an important and meaningful
distinction between two significantly different phases of the work on
resolving an issue.  In particular, it means my hands are (mostly) free
to work on something else.

>>> The co-ordination of development, and communication to stake-holders
>>> of what's going on, are important parts of our process. To dismiss
>>> them out of hand as "not about development" strikes me as painfully
>>> limiting.  Jira is a tool as much for our customers (reporting bugs
>>> and getting feed-back on whether and when we're going to do anything
>>> about them) and our managers as for us.

> [ . o O ( BINGO! ) ...  ]

I really don't get what you think is a "Bingo" about this.
Is it really such a shocking revelation that our team wants to
co-ordinate work in a way that gives managers a sensible way to
understand what progress is happening ?

In any case *it was right there in my initial mail*, so should be no
surprise.

>>> The addition of an "In Review" state would make it easier for me to
>>> communicate, to everyone with an interest in my work

> It doesn't communicate that to me, and I *am* actually interested
> in your work. A counter-example. The statement is wronmg.

Well, if your interest in my work doesn't stretch to watching the issues
I'm working on, I grant I'll fail to communicate to you.  Still, I'll be
making my best reasonable effort to communicate.  Perhaps you'll be
watching relevant parts of the source tree in Gerrit, so you'll know
it's in review that way.  In the mean time, having a state change would
enable me to communicate to those whose interest is active enough that
they chose to watch the Jira issues I work on - and your only objection
of substance, thus far, is that you get e-mails that take up your time,
which becomes a void objection in so far as you aren't watching the
relevant issues.

Meanwhile, throughout our industry, there are common processes by which
teams work together, such as scrum, that are designed to make it
possible for a team's managers to have a reasonable sense of what's
going on, while trying not to intrude too much in the team's actual
work.  For any team working in any of those ways, the distinction
between "hacking on this code most of the hours of each working day" and
"waiting for comments from others, sporadically taking time away from
other work to address those comments" is hugely significant to tracking
how their time is being used and how available they are for other work.

>>> something that at least two of them have made clear they want to know
>>> (and that I have commonly wanted to communicate).

> I am not convinced. But I am fairly sure that any rule that implies
> that any pair of two out of the One Million Verified Qt Accounts can
> introduce a new JIRA state will sooner or later necessitate some
> communication with Atlassian.

You are, again, making a silly point by wilfully misinterpreting what I
said.  I'm not suggesting that *every* change that's got two proponents
should be listened to.  I know of two definite watchers of my work who
would benefit from this information.  I suspect there are many others.
I am fairly sure that I am not the only developer of whom similar is
true.  Indeed, it seems likely to me that *most* developers' team-mates
and managers do care about the distinction between "I'm busy with this"
and "I'll be distracted by this from time to time until review is sorted
out, but I'm now free to focus on something else".

>>> I naively imagine other teams have similar needs.

> I am naively envying you.

I've no idea what point you're trying to make, or why you would
(ironically or otherwise) claim to envy me for this.

On Wed, Feb 19, 2020 at 10:43:17AM +0000, Volker Hilsheimer wrote:
>> Even when doing development (as opposed to the pointy-haired work), I
>> benefit from having tools that help me to maintain a work-in-progress
>> limit, that allow me to see what state the work someone else is doing
>> is in (because I might depend on it or just be curios about it), or
>> allow me to signal to customers waiting for the fix that they might
>> want to have a look at a proposed change, even if they don't have an
>> account on Gerrit.

André Pönitz (20 February 2020 00:08)
> *Customers*, *without an Account*, to *look* at changes on Gerrit?
>
> Sometimes I really regret having dropped out of university before
> finishing basic maths.

Again, no idea what point you think you're making here.
Volker's point is that customers (and other users) may find this information useful.
That *includes* (but is not limited to, as you try to make out) those without accounts.
And yes, both those with and those without accounts can find this useful.

>> The Qt Project defines “code review” as an explicit step that
>> contributions have to go through.

> Correct.

So why not show it, as a significantly different stage of our work, in Jira ?

>> Given that it takes a substantial amount of time to get things
>> through review,

> A review, even a *proper review* by *your standards*, does not have
> to "take substantial amounts of time".
>
> It's technically completely feasible (and I guess one could dig out
> practically examples) where an issue goes from "Someone mentioned
> a problem on IRC" to "Fix is integrated" in less then five minutes.

This is a rare case.
Indeed, we do actually have a recommendation - or is it a rule ? - that
one is meant to leave something in review, even if it has a +2
instantly, for long enough (typically a working day) to let interested
parties actually review the change.  So, while we surely make exceptions
to this for anything trivial/urgent enough, this is unlikely to ever be
more than a rare case.

The common case is that review and integration take several days,
or weeks, or months.

> The undeniable fact that it actually *does* take a substantial amount
> of time *in a lot of cases* is not the result of having "not enough
> JIRA states"

*NOBODY* has claimed that it is, so you're distracting the conversation
with an utterly irrelevant digression.

> but actually that of a lot of causes, none of which that I am aware
> are of of the sort that would benefit from changes to the JIRA
> process.

Nobody is suggesting review would go faster if we add an In Review state
to Jira; the point (repeatedly given, though you seem to treat it like
it's some shocking revelation) is to *communicate* something that is in
fact of interest to plenty of stakeholders.

>> I think it would make the JIRA-model of how work happens a bit more
>> useful if it would reflect the way that work actually happens.

> That's an interesting puzzle to solve when "the way that work actually
> happens" is actually "outside JIRA, for a reason"
>
> And that happens to be rather normal when e.g.
>   - the issue is not coming via JIRA, like normal reviews,
>   - the issue is urgent so JIRA would be too slow to use,
>   - the issue is small, so the overhead would be prohibitive
>     compared to the cost of the actual work.

and all of this is irrelevant to the current discussion, since these are
precisely cases in which we're not using Jira so the inclusion of an "In
Review" state would make exactly no difference.

>   - the issue is big, so wind direction would change to often
>     before this is done.

Not really sure I know what you mean by that; but if an issue is going
to take significant time to resolve, it usually is a good plan to put it
into Jira as a way of co-ordinating with others who have an interest in
it - including management.

	Eddy.