Writing up better issues

[Kriti Godey]

Hey everyone,

Now that we’ve launched and are building more of a community on GitHub, I think we need to put more effort into making sure that our GitHub issues are clear, readable, and self-contained. This will help users better understand what we’re planning and working on. Remember that ~90% of users will read documentation that we have available, but probably not engage with us.

I’d like all issues to:

• Clearly define the problem (including steps to reproduce the problem if it’s a bug)
• Clearly define expected outcome (what needs to be done to mark the issue as complete)
• Clearly specify any relevant research, design or product work, and how to share that with the team.
• Link to any relevant resources and discussions (on Matrix, the wiki, mailing lists, etc.)
• Have labels that indicate who can contribute (ideally, all issues should either say they’re restricted to maintainers or open to contribution i.e. help wanted)

Are there other things that would make sense to include?

It might make sense for someone to write up some issue creation guidelines as a reference for the team. We could also create/update issue templates for different kinds of issues.

Please let me know your thoughts / what would be helpful for you.

Kriti

[Rajat Vijay]

> Have labels that indicate who can contribute (ideally, all issues should either say they’re restricted to maintainers or open to contribution i.e. help wanted)

Does that mean going to those issues one by one and making sure to have at least one of those two labels? There are 97 such issues.

[Sean Colsen]

A few thoughts:

• ideally, all issues should either say they’re restricted to maintainers or open to contribution i.e. help wanted

• This is not how I’ve been operating. I do end up creating tickets sometimes which don’t have a help wanted label or a restricted label. Those tickets are more difficult than tickets which I label with help wanted, but easier than tickets which I label with restricted. I basically have four levels of difficulty:

  • easy => help wanted good first issue
  • medium => help wanted
  • hard => (no such labels)
  • extra hard => restricted

  I appreciate having four gradations of difficulty, but I’d be okay with collapsing them to three if that’s what others want. If we decide to retroactively enforce some XOR logic here, I’d want to be the one to look through the nonconformant tickets which I’ve authored so I can decide whether they would be more appropriate for restricted or help wanted.

• The other bullet points in your list provide a fairly accurate description of the process I already have for creating tickets. Kriti, I’d be curious to see any examples you have of tickets that I’ve authored which do not meet your threshold of excellence. It’s ok to share those examples publicly, too. Seeing examples might help us all build a collective understanding of where that bar lies.

• I don’t think we need to be as scrupulous when making restricted tickets though. For example, here are a few rather terse restricted tickets that I’ve authored.

  • Refactor Row type to use a discriminant property
  • Display fetch errors to user on the Table Page
  • Use display options in record summaries

• Personally, I’m satisfied with the level of detail that I see in our tickets.

  If I could waive a magic wand and improve one thing about our ticketing, it would be to balance the ticket authorship more evenly across the team. Qualitatively, I have a sense that I tend to create a lot more tickets than most people on the team. One consequence of that imbalance is that I tend to get roped into a lot of discussions and PR reviews with community members by virtue of being the ticket author. So personally, I would appreciate it if other team members would make an effort to just create more tickets. If we raise the bar for ticket quality, I’m worried that ticket quantity may end up suffering as a result. Enforcing a standard of quality is more straightforward than enforcing a standard of quantity, so if we say, “hey, your tickets need to be really detailed” then people might just decide to hold on to that ticket idea for a bit longer before putting it out there. This could have an unintended consequence of reducing the sort of openness and transparency that I think you’re after, Kriti.

​

[Kriti Godey]

Thanks SJ! Adding the mailing list back in so that other people on the team can see your suggestion.

On Sun, Apr 9, 2023 at 1:43 PM Samuel Klein <met...@gmail.com> wrote:

You might also estimate the size + complexity of the issue (1 hour, 1 day) -- some [complex details] tag as the opposite to  [good first issue] 

--
You received this message because you are subscribed to the Google Groups "Mathesar Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mathesar-develo...@mathesar.org.

--

Samuel Klein          @metasj           w:user:sj          +1 617 529 4266

[Kriti Godey]

Sean said:

The other bullet points in your list provide a fairly accurate description of the process I already have for creating tickets. Kriti, I’d be curious to see any examples you have of tickets that I’ve authored which do not meet your threshold of excellence. It’s ok to share those examples publicly, too. Seeing examples might help us all build a collective understanding of where that bar lies.

Personally, I’m satisfied with the level of detail that I see in our tickets.

The ticket which prompted my email was this one and the others in the installation project. I don’t mean to single Mukesh out – so far, our GitHub issues have been focused on tracking our work and not on providing context to a larger community (here’s a particularly egregious example that I authored).

Different people on the team write tickets with a different focus – Sean, I think your tickets do usually meet all the criteria I’ve laid out. I’d like everyone else’s to do the same (including mine).

Let’s use this ticket I linked to earlier as an example. The expected outcome is not clearly specified (what are “production services”?) and the larger context is not mentioned anywhere (the installation improvements project, related email threads or documents, etc.) Also the ticket also doesn’t specify auxiliary work (e.g. if we update our docker compose file, we also need to update documentation, let everyone on the team know if the dev workflow changes, etc.)

Let’s pretend I’m a potential Mathesar contributor. The contributor guide told me to go look for issues marked status: ready. I look at this issue and I don’t know what to do next. If I encounter enough of these, I’m just going to go contribute somewhere else.

Okay, then we might just want to mark this as restricted: maintainers and still not add any more detail. That would avoid the problem of community contributors working on the wrong thing.

But now let’s pretend I’m a potential Mathesar user. I want a Docker compose file that works a certain way. I search the issue tracker for Docker and encounter this ticket. But reading that ticket doesn’t give me any information on what the outcome will be. If it was clearer, I’d be more tempted to comment or engage. But as it stands, I’m like “what are production services? this is too vague, I don’t know what it means”, then I consider opening a ticket describing my problem but realize it will take me too long to articulate. Finally, I close the tab and end up going and doing something else (unrelated to Mathesar).

This is bad! We want tickets that are clear enough to grab the attention of our users and allow them to comment on them. Like this one or the comments referenced in this one.

Does this make sense?

Qualitatively, I have a sense that I tend to create a lot more tickets than most people on the team.

I agree this is a problem, but I think we should solve that separately. Team members are going to be responsible for creating tickets for projects they’re working on, so everyone will be creating tickets. I think it’s okay if creating tickets takes a little longer at first, people will get faster and more comfortable with practice.

I appreciate having four gradations of difficulty, but I’d be okay with collapsing them to three if that’s what others want.

Based on Pavish’s response in the repo admin thread and SJ’s suggestion, it might make sense to pull the labeling out into a separate discussion. It seems like a more complex issue than just difficulty.

Rajat said:

Does that mean going to those issues one by one and making sure to have at least one of those two labels? There are 97 such issues.

Once we come to a conclusion, we should do that, yes. We should do an audit for all our issues based on this discussion, but it’s probably not high-priority.

[Dominykas Mostauskis]

I think creating issues well is a big deal. I've some concerns though.

Sean's #2377 is an awesome issue, but its purpose and audience only match around 1/50 issues I write, in that it's a spec document for a user-facing feature. I'd say an issue like that needs to target the frontend team, other teams (if their work is required or they're affected), and outsiders, both technical and semi-technical (because they might be interested in feature changes, but not implementation details).

Most issues I write are for implementation details and related tasks. They target mostly me, but also people that might take over my tasks (usually the backend team) and whoever is auditing (backend team and Kriti, most likely).

And I sometimes end up with issues without bodies, like the one you linked, Kriti, as a counterexample. And I think that's fine, since they're always linked with a meta ticket, which has the necessary context. One of the reasons why I use issue linking is to not have to provide context redundantly. But that's a bit beside the main thing I'm trying to bring up.

To summarize my concern, should each issue target the broadest set of audiences? If so, I'm willing to experiment with that, but I'm concerned that that will make issue writing inefficient. If not, I think it would be helpful to specify in these guidelines when to target which audiences.

[Kriti Godey]

Your concerns make sense, Dom, thanks for sharing.

I think it would be helpful to specify in these guidelines when to target which audiences.

Agreed. I don’t think every issue needs to target every audience, but I need to think further before I can articulate where to draw the line.

I think the best next step would be for someone to draft an “Issue Guidelines” page on the wiki and send it out for feedback. Does anyone have the time and interest in doing this? If not, I’ll do it when I next have time.

In the meantime, please continue to send any thoughts and feedback about this topic to this email thread.