Proposed changes to GitHub issues workflow

Skip to first unread message

Sean Colsen

Nov 16, 2023, 3:49:43 PM11/16/23
to Mathesar Developers

Hi team,

Since our team meeting where we discussed our GitHub issues workflow, I’ve been considering some changes to our process and chatting with Kriti about it.

This email is to propose a set of changes that I hope will offer some incremental improvement to some of our processes — especially for repo admin and product/ux design work tracking.

I would like all maintainers to respond to this email with approval or critique of my proposal below.


This proposal does not attempt to address all the problems that people raised in our meeting.

Notably, it does almost nothing to address the problem of those thorny issue loitering in our main repo which don’t relate strictly to code-related changes. For example, appearing on Supabase’s integration website should not require any code-related changes and thus cannot be closed via a PR. I agree that it would be better to track these tasks somewhere else, potentially using a tool other than GitHub. However I won’t be proposing an alternate system (or working on researching one) any time soon. In the mean time, I’d like us to categorize these tickets as we find them using a new label called “non-code task”. Then eventually we’ll move all those tickets somewhere else and delete that label. Kriti may decide to take up the work of finding a new system for tracking non-code tasks.

Instead of addressing task management broadly, my proposal focuses on how we manage code-related tickets within the main repo.



I’ll begin by describing this proposal in terms of the changes I’d like to make to our issue labels. To review my proposed changes, please look at this diff:

On the left, you’ll see all our current labels, sorted and grouped for ease of comparison. On the right, you’ll see the set of labels as it would be after implementing my proposal.

Changes and rationale

  • We don’t seem to have a compelling use case for following labels so I’d like to remove them for the sake of simplicity:

    • restricted: design team
    • restricted: new maintainers
    • status: done
    • status: started
    • invalid
    • stale
  • It seems that we only ever apply “status: review” and “status: waiting” to PRs (never to issues), so I’d like to use the prefix “pr-status:” to more accurately represent the mutual exclusion between PR statuses and issue statuses. I also want to rename “waiting” to “revision” for better clarity.

  • I want to rework the remaining “status:” labels into a set of needs:” labels. This is really the meat of my proposal.

    Currently each ticket must be labeled with one and only one “status:” label.

    Under my proposal, tickets would be labeled either with a “ready” label (in green) or any number of “needs:” labels (in red). Using multiple “needs:” labels allows us to track work on the same ticket which can happen in parallel. For some tickets we might choose to move forward with UX design before product approval, or vice versa. Another way of thinking about this aspect of my proposal is that it changes the way we track product and design work, putting the tracking into “needs:” labels instead of “work:” labels.

    For me this tweak offers significant improvement. Here’s why… With separate “work:” labels for “frontend” and “design” (under our current system) we sometimes end up creating separate tickets to track design work from front end work. The extra ticket can be a nuisance, and it also can’t be closed with a PR, meaning it doesn’t quite fit the rubric for inclusion in the repo. In other cases we end up labeling one ticket as “work: design” and “work: frontend”. But that approach is also difficult because it lacks an explicit way to track the status of the design work as distinct from the implementation work.

    Under my proposal, all “work:” labels describe code-related changes. Any non-code changes which must be completed first are tracked by applying and removing “needs:” labels. What’s convenient about this approach is that I can triage a ticket by applying several of these needs labels at once.

    “Implementation specs” is a new sort of “need” that I’m also suggesting we track. For example, I would apply that to Able to order on an unorderable field because we need to clarify our expectations for the code-related changes before moving into implementation. “Implementation specs” is distinct from “UX design”, and I’d make that clear in the label descriptions.

    With these “needs:” labels, our process for monthly product approval meetings and bi-weekly UX design meetings becomes clearer. It’s easier to filter and see which tickets need which kind of work to move them forward.

  • I’d like to broaden “type: housekeeping” to “type: maintenance” so as to encompass work that is focused only on refactoring.

  • I’m also proposing (and this was Kriti’s idea) that we consolidate “work: backend” and “work: database” into “work: backend” because we don’t seem to require a distinction for our ticketing workflow. (Please correct me if I’m wrong, Brent or Anish.)

  • “work: release” is also getting the axe because it doesn’t seem related to code changes. We can track these kinds of tasks in whatever other system we come up with.


In addition to the above labels, I’m proposing that we enforce the following logic with our GitHub labels:

  • (A) We only create tickets in the main repo for code-related changes.

    If community members create tickets for non-code-related changes, then we can handle them as needed. I’m not sure I’ve ever seen a case like this, but I can imagine a user asking a question about how to use Mathesar by opening a ticket. We could potentially convert that to a discussion (which is the appropriate use-case for discussions, as far as I’m concerned), or we could leave it as a ticket. But we can address this situation as it comes up if it becomes a problem.

  • (B) Every ticket should have at least one “work:” label.

    And ideally tickets should only have onework:” label. This to better separate PRs for review, though it’s not always possible.

  • (C) Every ticket should either have a “ready” label or at least one “needs:” label.

  • (D) Every ticket should either have either a “restricted: maintainers” label or a “help wanted”

To start, I’d be enforcing the rules above manually. But I might consider adding some automation if manual enforcement becomes burdensome. We already have rules like this though, and manual enforcement isn't too bad.

How this affects community contributors

  • Another problem I often face is responding to community contributors in tickets like Column endpoint is slow when columns are many. Here a community contributor has expressed interest in helping with a ticket which is not labeled as restricted or as help-wanted. Rule (D) would help with this by eliminating that middle ground.

  • Rule (C) also makes it clearer to community contributors which tickets are ready for work and which are not.

This has the net affect of making it much simpler for community contributors to find tickets to work on — they need to look for tickets labeled “ready” and “help wanted”. We can direct them to a filtered list of those tickets easily instead of describing a set of logical steps to perform in order to determine if a ticket is suitable for contribution.

Kriti Godey

Nov 17, 2023, 5:44:51 PM11/17/23
to Sean Colsen, Mathesar Developers
I don't have any comments, since we already discussed this on a call. Good work on this!

Sean Colsen

Nov 21, 2023, 9:08:30 PM11/21/23
to Kriti Godey, Mathesar Developers
Reminder: I still need responses from Anish, Brent, Pavish, and Ghislaine.

Pavish Kumar Ramani Gopal

Nov 21, 2023, 11:56:48 PM11/21/23
to Sean Colsen, Kriti Godey, Mathesar Developers
I think this looks good.

Anish Umale

Nov 22, 2023, 7:53:02 AM11/22/23
to Pavish Kumar Ramani Gopal, Sean Colsen, Kriti Godey, Mathesar Developers
I agree with your proposal sean.

Ghislaine Guerin

Nov 22, 2023, 8:36:21 AM11/22/23
to Anish Umale, Pavish Kumar Ramani Gopal, Sean Colsen, Kriti Godey, Mathesar Developers
I agree with your proposal Sean. Thanks.

Kriti Godey

Nov 22, 2023, 11:34:55 AM11/22/23
to Ghislaine Guerin, Anish Umale, Pavish Kumar Ramani Gopal, Sean Colsen, Mathesar Developers
Let's just go ahead with this since we discussed it at today's meeting and Brent did not have any objections.

Sean Colsen

Nov 22, 2023, 1:49:24 PM11/22/23
to Kriti Godey, Ghislaine Guerin, Anish Umale, Pavish Kumar Ramani Gopal, Mathesar Developers
Cool. Thanks. I'll implement the new structure when I return from vacation.

Sean Colsen

Dec 5, 2023, 12:04:30 PM12/5/23
to Kriti Godey, Ghislaine Guerin, Anish Umale, Pavish Kumar Ramani Gopal, Mathesar Developers
I'm moving ahead with these changes now. There may be a period of a day or two before things are totally clean because I can't update the labels atomically. I'm working on cleaning up the labels first. Then after that I'll be updating the developer docs. Until all the dust settles, we run the risk of confusing some new contributors. But hopefully this time window will be small.

On 11/22/23 11:34, Kriti Godey wrote:

Sean Colsen

Dec 6, 2023, 10:51:08 AM12/6/23
to Kriti Godey, Ghislaine Guerin, Anish Umale, Pavish Kumar Ramani Gopal, Mathesar Developers

Ok, most of the dust has settled around the new labeling scheme, and I’ve updated the dev docs.

We have a few remaining next steps, which don’t need to happen right away:

  • Someone should move the non-code task issues out of the mathesar repo.

  • The backend team should clean up the remaining draft issues.

  • I still need to develop a more robust workflow for ensuring that all tickets have valid combinations of labels. For example, nothing should be labeled “help wanted” if it has a “needs:” label. There are number of different rules like this to validate. I plan to develop a slightly manual workflow for ensuring validity, built around GitHub’s CLI, but I still need to flesh that out. I may end up automating this eventually after I’ve further honed my manual solution.

If you notice anything else that needs to be done, please let me know.

Kriti Godey

Dec 6, 2023, 11:07:33 AM12/6/23
to Sean Colsen, Ghislaine Guerin, Anish Umale, Pavish Kumar Ramani Gopal, Mathesar Developers
Thanks for the update and work on this, Sean!
Someone should move the non-code task issues out of the mathesar repo.

I'll do this after we discuss our Basecamp workflow on Monday.
Reply all
Reply to author
0 new messages