Proposed changes to GitHub issues workflow
Sean Colsen
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.
Scope
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.
Proposal
Labels
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:
https://gist.github.com/seancolsen/24ee956fa5b54bd397ff30d7f7bd3efa/revisions
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.
Rules
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 one “work:” 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
Sean Colsen
Pavish Kumar Ramani Gopal
Anish Umale
Ghislaine Guerin
Kriti Godey
Sean Colsen
Sean Colsen
Sean Colsen
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.