Rework "contributing" page for clarity and changes to community contributor workflow

[seancolsen]

Summary

This PR alters our Contributor Guide as follows:

• Modify our workflow for community contributors as follows:
  • Assign tickets to community contributors
  • Give community contributors 1 week to follow up after claiming a ticket
  • Stipulate that community contributors are to claim no more than 2 tickets at a time
• Move content from code-review.md to contributing.md which is intended for authors to read. This change narrows the intended audience of code-review.md to be only code reviewers.
• Tighten language across contributing.md, making it clearer and more imperative.

Context and motivation

As I've been opening a lot of "help wanted" tickets lately and fielding incoming comments from new contributors, I've been seeing some problems with our current workflow that I'd like to improve.

Some challenges that inevitably arise with community contributors

• (A) contributor calls dibs on too many tickets in parallel
• (B) contributor commits to working on a ticket but fails to follow through
• (C) contributor jumps on someone else's ticket, either via requesting dibs or via opening a PR
• (D) contributor wants to work on a ticket which someone has already abandoned but does not because they're not sure it's abandoned

Our current process

• We don't assign tickets to community contributors
• When a community contributor expresses interest in working on a ticket, a core team member replies to their comment with something like "sure, go ahead".

Problems I'm experiencing with our current process

• The Contributor Guide lacks clarity on our approach to handling the above challenges. For example, how many ticket do we deem appropriate for one person to claim before submitting a PR for any? How long does someone have to submit a PR after calling dibs? Our lack of clarity leaves new contributors to form their own assumptions about our approach, and it also leaves core team members unsure of how to respond to some of those situations.

• When a new contributor comments on a ticket with something like,

  I'd like to work on this, may I please be assigned?

  ...I find it tricky to craft a response. "Yes, you can work on it... But, no, we're not going to assign you to it." I imagine that might be confusing to some people. I've found myself attempting to explain why we don't assign tickets, and it's a bit cumbersome.

• Addressing challenge (A) is difficult without assigning tickets. Sometimes I hesitate before confirming that a new contributor may work on a ticket. "Hmmm, I think I've seen this person before", I might think. But I don't have a good way of asking GitHub how many tickets that person is already working on. With a workflow that utilizes assignments, I can easily answer that question.

• Addressing challenges (C) and (D) become more murky and subjective. If the ticket is unassigned but has a "dibs" comment 1 week ago, can a new contributor work on it?

Problems with assigning tickets (and my plan to address them)

• We moved away from assigning tickets mostly due to challenge (B). We didn't want to manage the overhead of un-assigning people from tickets.

  Well, I'm here to say: I want to manage the overhead of unassigning people from tickets. I'd like to roll this into my triage work. If it's not easy, I'll find a way to make it easy. I've been using gh for my triage work and it's been great. I'll try something similar for this new task where I look for tickets that were assigned to community contributors over 1 week ago without any PR or comment. It'll take a little massaging to get right, I'd rather take on that mess than the mess I currently have responding to new contributors with our current workflow.

[kgodey]

Workflow

With the current workflow, I wanted to eliminate the concept of contributors calling dibs on tickets. If people want to contribute, they can submit a PR. If we manage to actually communicate this workflow effectively, it would eliminate the challenges you've listed and also not need tickets to be assigned / unassigned. This seems like less work for us.

That being said, I think the workflow you've proposed is fine. I don't have the time to manage ticket assignment, but if you're fine with doing it, that works.

Overall

I think this page looks a lot better! Thanks for your work on this.

[seancolsen]

@kgodey

eliminate the concept of contributors calling dibs on tickets

I can appreciate the simplicity that paradigm would bring to our work, but in an organic, community-focused environment, I don't think we can realistically expect that workflow to feel natural or respectful. Take this thread for example. Two contributors expressed interest in working on the same issue on the same day. If we're entirely eschewing the concept of "dibs", then responding to those contributors in a welcoming manner feels hard to me. Any response that falls short of delegating the work to one contributor feel like saying "okay you two, please duke it out and see who can submit a PR first".

I originally liked the idea of forgoing assignments, but in responding to lots of people lately, I'm coming to terms with the inevitability of managing some form of "dibs", however implicit they may be. And the opinion that I've come to recently is that making those dibs explicit will likely require less work for us than making them implicit.

[seancolsen]

Alternatively, if we really do want to lean into the "no dibs" approach. We might try modifying our contributor guide to tell people not to comment on tickets. And to tell core team members to respond to such comments with something like

Thanks for your interest in helping! You're welcome to submit a PR.

Note that, as a matter of policy, we do not attempt to prevent multiple community contributors from working on the same ticket in parallel. Until we have merged a fix for this, anyone else is free to take up this work too.

I would be open to this approach if we make it clear within our documentation and communication. It just feels more cut-throat.

[kgodey]

@seancolsen I do agree that the "no dibs" approach risks duplicated or wasted work, but it seems largely theoretical to me. The majority of people who comment on tickets don't seem to follow through. I didn't want the team to do extra work to manage issue assignment to mitigate what seemed to me a minor risk.

Anyway this is just an explanation of my thought process behind the original workflow. I don't think it's as relevant now because we're not rotating comms responsibilities like we were when we set this up. I'll leave the decision on what our contributor workflow should be to you.

[seancolsen]

@kgodey

• I re-worded the "Claim the issue" step as follows

  (Optionally) Claim the issue.

  If the Mathesar team has already merged one of your PRs, then you may wish to ear-mark the issue for yourself so that other do not work on it concurrently.

  However, if you are band new to Mathesar, we recommend skipping this step and making your changes without claiming the issue. (A core team member will assign the issue to you after you open a PR.) This recommendation is designed to reduce the overhead the core team has experienced from a high volume of contributors failing to follow through with their intent to submit PRs.

  If you decide to claim the issue:

  1. Comment on the ticket, saying "I'd like to work on this" or similar.
  2. A core team member will assign you to the ticket.
  3. At this point you have one week to follow up. If we don't hear from you by then, we will unassign you from the ticket so that others may claim it. If you need more time, you can ask for an extension, explaining the progress you've made and the challenges you've encountered. If you have not begun work at all, then we will need to unassign you.

  Please do not claim more than 2 issues concurrently before submitting PRs.

• I'm hoping this will strike a good balance while also placing the ball in the contributor's court. I.e. I don't intend to validate whether contributors are eligible for claiming tickets. My hope is that the text within this step will serve to dissuade some of the fly-by dibs-claimers

• Since you said:

  I'll leave the decision on what our contributor workflow should be to you.

  I'm going to go ahead and merge these changes and begin assigning tickets to new contributors henceforth. We'll see how it goes. I'm happy to take this on.

[kgodey]

Sounds good, thanks @seancolsen.