Repo management guide and triage team (GitHub Gardening)

[JimMadge]

Traditionally, The Turing Way has had quite loose and permissive rules/processes when it comes to how to use GitHub and its features. For example, issues may be used for reporting bugs, creating tasks, a discussion, recording notes, drawing attention to an event and so on. Management of issues/PRs/discussions is ad hoc and there isn't a team to handle them.

Importantly, part of this is by design, to create an environment where people are not punished for doing "the wrong thing" and all community members are empowered to contribute in different ways.

It does, however, lead to some problems like,

• Large numbers of open Issues/PRs
• Difficultly filtering and finding items
• Duplicates
• Stale issues and PRs, where there is little likelihood they will be closed
• Irrelevant (may not be quite the right word) issues where there is no task, no definition of done
• PRs marked as ready for review when they are in a draft state
• Poor/inconsistent use of labels
• PRs with no reviewers assigned
• Underuse of Discussions for items like questions, suggestions, discussions

And more holistically this means,

• Navigating the repo is difficult or confusing
• Repo is intimidating (where to start with so many issues?)
• Work gets lost/forgotten about or overlooked
• Work may be merged before it is ready

I think we should consider how we would like the repo (or all repos in the community) to work, and how some more rules/guidlines and enforcement can help. The output would likely be a section in the community handbook for repo management/triage. That way, the rules are clear and we maintain the spirit of enabling people to contribute (in fact, better than before because there are clear guidelines for someone to follow!).

I also think this is more important than ever as we move to relying more on volunteer effort.

[JimMadge]

My proposal would be we have a team, who regularly triage issues/PRs/conversations. We would create the team in the organisation and grant everyone in that team the "triage" role (which I think should be sufficient).

We will write guidelines in a section of the community handbook. These will explain the spirit of our rules and detail what should be done. Tasks will include,

• Assign labels
• Suggest reviewers
• Close won't fix, not enough information, etc.
• Mark PRs as draft if they aren't ready for review
• Move questions/discussions from issues to discussions

We will write checklists for each "item" (Issue, PR, Discussion, and so on) for triage team members to follow. That way, following the guidelines is fast and easy.

Triage team members will once a week (or less often?) spend 15–30 minutes (?) working through Issues/PRs/Discussions from newest to oldest applying the checklist.

[RayStick]

I like these suggestions, and agree that the "triage" role is appropriate for these activities.

We should encourage people to follow the guidelines for Issues & PRs themselves if they can, but this team could be there to (1) check or (2) implement (when following these guidelines may become a barrier for people contributing).

I am pro draft PRs, Issues template and PR templates (with a checklist to help an author know if a PR is ready). Perhaps we'd need to think about which types of contributions require more strict checklists versus others.

[JimMadge]

We should encourage people to follow the guidelines for Issues & PRs themselves if they can, but this team could be there to (1) check or (2) implement (when following these guidelines may become a barrier for people contributing).

Yes exactly! I think that is something we should focus on when writing about this. It isn't about punishing people for doing "the wrong thing", but instead organising things well so there is the best chance possible that things get seen and resolved.

[aleesteele]

@JimMadge - This is a fantastic idea! We had a reviewers and editors group a few years ago that did this kind of active pruning of the GitHub repository, and it sounds like we're in a much more mature place to do this kind of work now: #2633

There are lots of Community Management folks interested in this kind of work - so this could be a great overlap between the two groups.

[yabellini]

May I suggest that you use issue templates? This way, whoever creates the issue has a guideline for what information is needed for it to be useful.

You can have several templares for different type of issues and repos.

[JimMadge]

That is a good idea. I believe we can also add labels and assign people in templates, which would help get new items in a good state before triage.

The newer issue templates render as a web form too, which is nice as you're not asking people to edit a Markdown template.

[Arielle-Bennett]

Just want to flag that we do already have several issue templates available formatted in YAML to help support people in opening issues, but it would be worth revisiting these to see if they're clear, or other templates might be needed: https://github.com/the-turing-way/the-turing-way/tree/main/.github/ISSUE_TEMPLATE

We also have a PR template but it is lightweight and so I think would benefit from an update to include checklists etc

[RayStick]

We could reflect on whether some automations could help. For example, I have been using a workflow that automatically assigns a label to a PR if a PR edits a specific file - for example, if the README file is edited, the 'Documentation' label will be automatically assigned.

[JimMadge]

Already seeing a theme that implementing our guidelines through issue and PR templates is a popular idea 🚀.
That feels like our value of "making it easy to do the right thing".

[bsipocz]

I think we should also seriously consider revising when to give write access to the repo. Nowhere else are so many people with write access. While this lowers the barriers to contribute to practically zero, it also opens up the whole repo to serious security risks either by accident or even malicious intent.

Not giving why access by default would also mean much cleaner branch history, and the reassurance to contributors that they cannot mess anything up (that maybe just me, but it was reassuring for me when I was github newbie that I cannot in fact do anything wrong, all I'm allowed to do is OK to do, which is not really the case for github novices with write access).

[aleesteele]

Good question @bsipocz - we should bring this to the next community forum. There were strong cultural norms behind adding folks manually to the repo at the beginning of the project (cc: @KirstieJane), but we might have reached a different point of the project by now!

[aleesteele]

Flagging for the @the-turing-way/community-management-working-group - this is relevant for folks interested in assisting with Github repository maintenance. Adding breadcrumbs to this issue: #4161

[aleesteele]

These sorts of discrete tasks and checklists sound very valuable. We have an emerging schedule that we'll be adding to Github as well as checklists that may be useful in organising this group as well: https://docs.google.com/spreadsheets/d/1gw7U6remchz-yagCoJ51A2uHxofi4aLsq4trX-9XcBE/edit?gid=103152445#gid=103152445

[acocac]

I support the idea of the triage team where Infrastructure and Community Management WGs (+volunteers from other groups?) work together. I propose expanding/updating some sections of the community handbook to document the triage process. We could create a new section within Infrastructure to include the guidelines. The section should be connected (crossreference) with other relevant sections e.g. Contribution workflow.

Re time commitment, because of the new structure, I suggest prioritising the core repository for weekly meetings (15-30min), and consider monthly revisions for the remaining repositories.

[JimMadge]

That sounds good. My only comment would be the process shouldn't go in the Infrastructure chapter as it doesn't fit with the way we use infrastructure to talk about hosting, CI, and so on.

[JimMadge]

Discussion with @the-turing-way/community-management-working-group:

Enthusiasm in that group for being part of and establishing a triage/maintenance/gardeners team.
Aim to set some rules/expectations and formalise this work. Lots of ideas for how to document this in the book, use GitHub projects to help do this work, what we should use issues/discussions for 🎉.

Next step is to write the initial checklists for triaging issues/PRs/discussions at the collaboration café on 2nd July.

[JimMadge]

Draft checklists and guidance

# GitHub Gardening

Instructions and information for gardeners

Guiding principles

• Upskill contributors, teaching them best practices
• Be a mentor
• Be a human
• You are not "GitHub police"

GitHub item purpose

Issues

• An issue is a task
  • Of a reasonable size for one person (or, a list of sub-issues)
  • Which has a clear "definition of done"

Discussions

• Items for discussion (not necessarily tied to action or implementation)
• General questions
• Ideas

PRs

• A proposal to merge one branch into another
  • Marked as a draft if it is work in progress
  • Marked as ready to review if you feel it is ready to be merged
    • [name=Arielle] if it's draft do the CI tests still run on it?

Gardening stages

These stages correlate roughly with how mature an item is.
It isn't a law, but is intended to help us understand what stage an item is at and what we should be aiming to do to help contributors at each stage.

Growing/sowing

Initial actions to ensure an item has the best chance of success

Fertilising

Working on active items to help push them over the line

Pruning

Closing items which have gone stale

Glossary

Stale issue
: A stale issue is

Checklists

Issues

Always leave a welcoming, friendly message to explain what you are doing and why

Growing/sowing

• Is this an issue
  • Move to a discussion if this is a discussion
  • If there is no definition of done
    • Ask if we can find one
    • Move to a discussion(?)
    • Close as unfixable
• Is this issue in the correct repository
• Assign appropriate labels
• Tag (or assign) relevant community members

Fertilising

• Ensuring issue is "in action"
  • Post in the issue
    • Is anyone working on the issue, has anyone been assigned?
    • What support does the contributer need to fix the issue?
  • Suggest actions
    Invite to post a Slack message
    Invite to collaboartion cafe
    Link with another community member

Pruning

• If the issue is stale (we should define stale) - I would hope we could automate at least some of this section
  • If there is no stale label
    • Mark as stale and leave a message
  • If there is a stale label and x days have passed
    • Close the issue as stale

PRs

Growing/sowing

• Is this a PR
• Assign appropriate labels
• Convert to "Draft" or "Ready for review" as appropriate
• Assign reviewers
  Or tag people who may be interested

Fertilising

• Getting the PR "over the line"
  • Reach out to the contributor.
    How close are they to finished?
    What support do they need to finish?
    Do they have the time to complete this PR?
  • Suggest(?) actions
    Invite to post a Slack message
    Invite to collaboration cafe
    Link with another community member
    Arrage for someone to "take over" the PR

Pruning

• Is there a relastic chance this PR will be merged?
  Are the contributors still engaged?
  Is the branch still well in sync with main?
  • Reach out to draw attention to these issues
  • Close the PR
    ⚠️ Closing a PR may(?) delete the branch which could result in loss of history on that branch

[JimMadge]

I feel we are all aligning on calling the group gardeners and using gardening terms 🌱

[JimMadge]

PR #4304