Reducing the friction of supporting, maintaining, and contributing to Octokit

[nickfloyd]

Hey Octokit friends,

This will probably be one of the least glamorous things to discuss; hopefully, it will increase the quality of life around supporting, maintaining, and contributing to Octokit git a bit better.

We've been looking for ways to reduce the friction around contributing and supporting Octokit for a while now. We can do several little things to increase our ability to service the roughly 70 repos that we currently own - one of those things is to drive toward consistency while ensuring each community still embraces its uniqueness around platform and language.

You might've come across our discussions around generative SDKs (here, here, and here) and how that will equip all of us to get more out of Octokit in a faster, more predictable way... Octokit.js already does this in many ways 🎉.

In the next few weeks, you'll probably experience some shuffling around some meta aspects (labels, PR and Issue templates, etc...) of the Octokit and Terraform repos.

We want to be sensitive and avoid unnecessary workflows and over-expressed processes - so as you see things change, please "mind the dust" and know that we are iterating on the "right" things for our community. We're hoping to do our best to avoid the whole first-order thinking reaction of tearing things down (see Chesterson's fence) and defaulting to a position of second-order thinking where we consider the intent an purpose behind what is already in place.

As an example of the need mentioned above, have a look at the current "picture" of how we label things below - having all of these various ways to label things not only cause challenges with shipping but, as you know, they can be stumbling blocks for both new and old contributors 😬 we don't want that.

Thank you all for making this one of the most welcoming communities in open source. If you have any thoughts or feelings about things you've seen work in other open-source projects (around process, consistency, etc...), please add them as part of this discussion so our community can chat about them.

Also, take time to call out any workflow or CI gotchas that could be problematic - we'll be going through these with a fine-tooth comb, but I am sure we'll probably miss some things.

[kfcampbell]

I'd like to offer a couple of opinions regarding labels in hopes of prompting more discussion here.

1. We should remove many labels and shoot to keep the smallest possible subset of useful labels.
2. Proposal for labels to keep:
   • Bug
   • Breaking change
   • Feature
   • Duplicate
   • Docs update only
   • Good first issue
   • Something to signify "blocked on upstream API support"
   • Something to signify "housekeeping/chore/dependency update"
   • A set of standardized sizing labels
3. I think ideally we'd standardize on a cadence of merging and releasing small dependency updates as well as a proscribed timeframe to respond to CVEs.

[gr2m]

• We should remove many labels and shoot to keep the smallest possible subset of useful labels.

Yes

• Proposal for labels to keep:

  • Bug
  • Breaking change
  • Feature
  • Duplicate
  • Docs update only
  • Good first issue
  • Something to signify "blocked on upstream API support"
  • Something to signify "housekeeping/chore/dependency update"
  • A set of standardized sizing labels

Other Labels that I think worked well for the JS repositories in the past:

• Maintenance
  • this is what we use for "housekeeping/chore/dependency update"
• Documentation
• Blocked
  • I think we should have a general "blocked" label, and then clarify with either sub-labels or an explanation in the issue

I think it's also helpful to have some language specific labels in order to group issues. For JS repositories that's typescript and deno. I'd like to add esm.

Another label that could be relevant for grouping across languages is "Enterprise". Other labels might be "REST" and "GraphQL", but we don't have a need for these two in JavaScript Octokit due to the multi-repo setup.

Lastly, I have a simple GitHub App that enforces a category label: "Bug", "Feature", "Maintenance". I wanted to add "Documentation" as another category label. The app also adds the issues based on the category labels to a project which I used extensively with my GitHub Manager while I was still a contracter on Octokit. Today I'd use the new Projects.

• I think ideally we'd standardize on a cadence of merging and releasing small dependency updates as well as a proscribed timeframe to respond to CVEs.

No strong opinion. For dependency updates I'd set the goal for no more than one week, at least for JS.

[timrogers]

Agree with @gr2m that we should allow the possibility of repo-/language-specific repos alongside the shared ones that we use across Octokit.

[nickfloyd]

Here is the current working set of labels: https://github.com/nickfloyd/repo-meta/labels

Here are the suggested ISSUE templates: https://github.com/nickfloyd/repo-meta/tree/main/.github/ISSUE_TEMPLATE

Try out the templates: https://github.com/nickfloyd/repo-meta/issues/new/choose

[gr2m]

I'd give all groups of labels the same color. And all labels that don't belong to a group I'd just make grey

[gr2m]

instead of "REST API Version", we could ask for GitHub Version, as in: github.com, GHES [VERSION], GHEC? Besides REST, APIs also include GraphQL, Webhooks, and Authentication/Authorization

[timrogers]

I think we should have both 😊

[gr2m]

Ahh wait, with REST API Version you mean the new not-yet-released versioning, right? Sorry I missed that at first.

There is a risk asking for too much stuff, but yeah, we could ask for both. It's another case where e.g. in github/graphql.js I would not ask for the REST API Version though, for example

[kfcampbell]

I really like the idea of GitHub versions! There's a decent amount of API surface differences between the various GitHub flavors.

[timrogers]

I think we should try, if possible, to avoid the word "chore". It devalues work that people (and us) are doing and it would be better to use more descriptive tags like "dependencies" or "docs".

[nickfloyd]

Agreed! I ended up going with Maintenance

[timrogers]

I'm not sure what we should use Status: Invalid as people might find that judgemental. I'd probably suggest just closing an issue or PR instead.

[timrogers]

How about "Needs more information"?

[gr2m]

I use invalid exclusively for spammy issues. spam might actually be a better label, more explicit, at least for how I use it.

[timrogers]

Spam is okay for the most egregious cases. I just don't want to upset people if they're trying their best!

[gr2m]

I just don't want to upset people if they're trying their best!

in that case I just wouldn't add a special label. I'd close it as "won't fix". Usually people file a bug or feature request, then we realize it's really a support request, so I remove bug/feature, add support, and close the issue when the discussion concluded

[timrogers]

I guess it depends on what we're trying to get to. Nick's mention of "incomplete" made me think that he was looking for a state when the issue does not have enough information.

[timrogers]

I'm not sure that "Good first issue" should be a "type" - I'd expect an issue to have a single type, and then this would be a "tag".

[kfcampbell]

Agreed! In my original comment I did not distinguish between "type" and "tag".

[timrogers]

For the JavaScript repos, when submitting bugs, I think ideally we would ask people to provide all of the Octokit package versions from their package-lock.json file (or similar). We often have issues that are related to particular combinations of versions.

[nickfloyd]

Good point... though I think that would be better encapsulated in PR or Issue content and not labels.

[timrogers]

Yes. This would be for the issue templates.

[gr2m]

Regarding issue templates: I'd like to adjust them based on the needs of the repositories. I think we can agree on a group of fields that should be present and use the same names for aggregation, but then we should be able to adjust descriptions and add additional fields etc as needed.

[gr2m]

Another category label we use a lot is "Support". I guess we could move these issues to discussions though.

What happens a lot is that folks open a bug report or feature request, and then we realize it's not actually a bug or the feature already exists or there is a better way to achieve what they want. In this case I change the category label from bug/feature to support.

What I don't like about transferring to discussions is that most often these issues can be concluded, while discussions are open ended.

[timrogers]

"Support" is a good point!

[nickfloyd]

Would support and question overlap in that case? If so, I think I'd prefer support over having both.

[kfcampbell]

I like the idea of taking support over question.

[gr2m]

yes, I never needed question

[nickfloyd]

We have implemented the changes as discussed across all Octokit and Terraform SDK repos.