Ticket descriptions in the issue tracker

Django Internals
1

I would like to respectfully propose a modification to the policy for approving tickets in Trac to ensure that when a ticket is moved to the triage stage of Approved the ticket description reflect the issue for which approval has been granted. When a maintainer approving a ticket concludes that the issue as reported is not valid, but that the ticket should be re-purposed for another (presumably related) issue, then the statement of the problem (or proposal, in the case of feature requests) should be updated to reflect what is required in order to resolve and close the ticket. I recently spent several days assisting the author of a pull request for a bug report, only for us both to learn that the issue for which approval was granted was a different issue than that contained in the ticket’s description, and the work on the pull request was to be discarded.

There would be at least two paths for applying this policy, depending on the issue. For some tickets, when the change in direction is relatively straightforward, the maintainer could simply rewrite the description him- or herself. For other situations, it might be more appropriate to add a comment indicating that the issue cannot be approved as stated, but a similar issue could be, provided that appropriate modifications were made to the statement of the problem and/or the acceptance criteria, leaving the work of rewriting to the submitter of the ticket (or some other contributor). I don’t believe the project is well-served by requiring that contributors mentally assemble the actual requirements for a ticket’s solution by assessing all the comments on the ticket and determining what the actual requirements are. Not only does that significantly increase the friction for contributing to the project, making it less likely that bugs will get fixed, but it would be rare for any two contributors to come up with exactly the same requirements from such a tedious exercise.

Is this the appropriate place for such a proposal?

2

Hi Bob, thanks for this. Yes, this is the right place for process feedback. I’m sorry you didn’t have a great experience this week. I really find nothing to disagree with in your proposal, so all I have to offer is a plea for some grace when things get tough.

For some tickets, when the change in direction is relatively straightforward, the maintainer could simply rewrite the description him- or herself. For other situations, it might be more appropriate to add a comment indicating that the issue cannot be approved as stated, but a similar issue could be, provided that appropriate modifications were made to the statement of the problem and/or the acceptance criteria, leaving the work of rewriting to the submitter of the ticket (or some other contributor).

I think if you look at other tickets, you’ll find this is largely what we do. To summarize, what happened this week, was that we had a first triage decision of “needsinfo” and then eventually a second triage decision with tentative language:

I’m not sure what this should do but I agree this is confusing and requires more investigation.

This shows significant uncertainty. There’s smoke, but I don’t know if the fire is here or there. It’s difficult to update the description of the ticket at this point when there’s this much uncertainty: perhaps, “See note about uncertainty in comment:6”? I do expect contributors to at least read the triage decision for caveats. So I would politely push back against the assertion that the triager knew that the issue was somehow separate or located elsewhere but just chose not to update the information in all places. It’s hard to make authoritative statements in the face of uncertainty, and all we can ask for is some grace.

When I noticed significant effort being put toward the PR, I dropped what I was doing to investigate, because I wanted to limit as much further frustration as possible. I confirmed the suspicions of the last triager, and tried to add clarity around that triage decision with the benefit of the additional investigation I had invested. At that point, the conversation was split between Trac and GitHub, so I just replied on both those channels. The moment for updating the body of the ticket had passed, or so it felt – but I take your point that I should still update the body of the ticket to help the next contributor. It’s been a busy week, but I’ll do that today. I hope that explains why I took the actions I did.

I don’t believe the project is well-served by requiring that contributors mentally assemble the actual requirements for a ticket’s solution by assessing all the comments on the ticket and determining what the actual requirements are.

This sounds attractive, but I’m not sure how to guarantee it. Doubts can emerge even after PRs are raised. A recent example is a long thread eventually leading to no consensus after multiple PRs proposing to change the decimal separator for the Swiss locale. “Assessing all the comments on the ticket and determining what the actual requirements are” was precisely the work needed. Call it triage, call it contributing, call it what you want, but it’s what that ticket needed, and we needed the help of volunteers to bring it to a resolution.

Finally, I think I do want to encourage contributors to digest all the comments on a ticket. Sarah Boyce’s advice to new contributors is to avoid tickets with loads of comments for precisely that reason: it’s a better fit for more experienced contributors willing to cope with more uncertainty. I also have to study the entire ticket thread myself before offering feedback. This means all of us have a corresponding duty to make points as concisely as we can to avoid creating burdens on others.

Thanks again for volunteering your time and talent toward helping other Django users. It’s much appreciated. Giving feedback to others in public is a precious commodity around here, and it’s to be celebrated and recognized when it happens.
With appreciation, Jacob

4 Likes
3

Good morning, Jacob. Thank you for your prompt, thorough, and thoughtful response. Very much appreciated. :folded_hands:

Yes, grace is always appropriate. :100:

I should note that I did read all the comments, including the one you quoted. But I didn’t read that comment in isolation. I read it in combination with the rest of the ticket, and came to a somewhat different interpretation than you did. Reading the approver’s comment in combination with the fact that the ticket was approved (with the problem description left as the original reporter submitted it), the take-home message I came away with was along the lines of “the approver agrees that the issue as described is a valid bug report, and the current behavior is indeed confusing and needs to be corrected, but she is uncertain about how the code should be modified to implement that fix—that will require more investigation.” I would guess that the author of the rejected PR came to a similar conclusion. I can confirm that identifying a correct solution did require a considerable amount of further investigation. :sweat_smile:

In other words, that comment without the ticket approval would have conveyed something altogether different to me (and to others, I suspect) and my interpretation would probably have matched yours much more closely. I do understand how you came to your interpretation of the comment’s meaning. I hope the understanding works as well in the other direction.

I would suggest that in this particular case it would have been preferable either to postpone approval of the ticket until the requirements and acceptance criteria had been modified so that they were eligible for approval, with explicit instructions in the comment identifying the deficiencies of the existing issue summary, or (as you hinted) to put a very prominent notice at the top of the ticket description along the lines of …

[N.B.: This ticket has been tentatively approved, but with the condition that the issue description be modified to resolve the concerns raised in comment #X. Do not attempt to create a PR based on the current description. This note will be removed once the description has been corrected.]

In my view, the first approach is the more straightforward option. And safer. And less work for the maintainer. But either approach would be an improvement over what we ended up with.

Finally, let me thank you for your offer to correct the issue description.

Warm regards,
Bob

4

I see that the description for the ticket we’ve been discussing has indeed been modified, though not in the way I was proposing here. I wasn’t suggesting that saying the ticket description is invalid should be a permanent solution. Would there be any objection if I were to offer to rewrite the description for that ticket myself?

5

Please do – I would just caution to keep the original report in some form, as otherwise it can be difficult to interpret the next half dozen comments, but use your judgment.

1 Like
6

I posted the fixed description. Basically, I went back and re-read Sarah’s comment, this time pretending that the ticket hadn’t been approved with the original description left unchanged, and that her version of the ticket’s title hadn’t still identified PostgreSQL instead of SQLite as the back end with the problem (part of the reason I hadn’t realized she intended to narrow the scope of the ticket). Using that filter, I interpreted what she wrote as meaning that

  • she was able to reproduce the bug; but
  • she was able to work around the bug using the string constructor; however
  • that workaround did not work with SQLite

You appeared to confirm that interpretation when you later wrote:

Results are consistent if you provide a string to the constructor, e.g Decimal("3.0").

So, following the view that Sarah’s comment was meant to narrow the scope of the ticket to make the workaround she came up with (which works with all four of the other back ends) work with SQLite as well, I’ve attempted to capture that as concisely and precisely as possible, preserving (as you rightly suggested) the history showing what the ticket was originally reporting, so that the earlier comments won’t be confusing.

I think this should make it easier to produce a PR which meets the new requirements. I hope you agree.