GitHub as a team sport

NHS RPySOC 2024

Matt Dray

22 November 2024

tl;dr

• GitHub organises code
• GitHub can help organise people
• We’re learning as we go

• ‘Too long; didn’t read’.

• GitHub isn’t just a dumping ground for code and version histories.

• There are features that can help with communication and collaboration.

• We’ve been learning what works for us as our team continues to grow.

Context

• I’ll start with background and motivation.
• What’s the problem we’re trying to solve?

The Data Science Team

• Expanding to 8, all remote
• Complex New Hospital Programme (NHP)
• How should we work together?

• We’re a growing team (soon to be 8).
• We’ve got different backgrounds and experiences.
• We do modelling, data pipelines, apps, etc.
• We work largely on a big, complicated project with lots of stakeholders and tasks.
• We want to bring other teams in the SU along with us.
• Are there tools or approaches we can use to help us?

The dream

• Order from chaos
• Good communication
• ‘Bus factor’ reduction

• We have a big project with lots of repositories. We have lots of different tasks and goals.
• We want to improve clarity and reduce the chance of misunderstanding and error.
• We don’t want information locked up in one person’s brain.

Living the dream

• This works (for now)
• New folks are joining
• Things can will change

• We’ve been slowly changing how we work and the tools we use.
• Our standards will make it easier for new starters, but they should also have an influence on how we do things.
• Nothing is set in stone. We’re continually thinking about what works and what doesn’t.

So, GitHub

• This is a talk about a widely used tool and how we’re making use of its features to meet our needs.
• I’ll give a few examples of some of the things we’re doing.
• I’ll start broad and get narrower.
• Examples, because there’s not enough time to talk about everything.
• We follow some basic GitHub like tenets ‘one issue, one branch, one pull request’ and ‘commits should be small’, but there’s some other things I wanted to mentionin particular.
• A lot of this will apply to other tools, like GitLab.
• I hope there’s one thing, big or small, that you might consider for your next project.

GitHub Projects

• We’re ‘agile’
• Many tasks/respositories
• We want to show progress

• We work in sprints.
• There’s lots to keep track of: the model, a couple of apps, a documentation site, etc.
• We want to show others how things are progressing.
• GitHub Projects helps us by arranging individual tasks from across lots of different repositories.
• We can also add custom labelling to help us organise and track.

• We can show the tasks in kanban style, or as a list or as a calendar.
• We can filter down to show only certain labels, statuses or assigned people.
• This is helps us find, organise and focus during sprint planning and weekly sprint catch-ups.

Division of labour

• The ‘scrum master’
• Owners and deputies (CODEOWNERS)
• Issue and pull-request assignees

• At the level of the sprint, we have a scrum master that oversees the movement of tasks from the backlog and takes us through the GitHub Project in weekly sprint catch-ups.
• Within each repository we have an owner and deputy on each repository, with the goal of keeping the it shipshape (e.g. good docs, no stale branches, PRs are reviewed).
• And we have people assigned to issues and PRs, which signals the tasks that people are working on.
• Having an identifiable person in charge makes it easier to identify ownership and for others to talk to the right person.

Task sorting

• MoSCoW method
• Release-aligned milestones
• Efficient triage

• Organising repositories at a higher level doesn’t preclude organisation at the repository level, which is foundational.
• We typically include the labels Must, Should, Could, Won’t (MoSCoW) to filter tasks and to help assess importance.
• The issues associated with the current sprint are added to a milestone with the upcoming version number. This makes it easier to focus, but also release the code with auto-generated notes.
• These approaches signal intent and help the team to more efficiently decide what to do next.

Pull requests (PRs)

• Talk!
• Use suggestions
• The assignee merges the PR

• Respect each others’ time. ‘Closes #10’ isn’t always enough.
• GitHub comments don’t replace talking. Discuss if unclear.
• Suggestions are efficient and respect the submitter.
• The submitter owns the PR. They’re responsible for closing it.

Surprise twist…

GitHub is a team member

• Automate with Actions
• Issue templates
• Repo templates

• Most of the team is human. GitHub itself has features that can automate away some boring things and help prevent accidents or forgetfulness.
• GitHub Actions for continuous integration. R-CMD check at least for R projects. Start with r-lib examples as a basis.
• We’re looking towards things like templates at the issue and repo levels; again to remove drudgery.

Be a good sport

Are we curling? 🥌

We:

• are a small team
• assume specialist roles
• work in sync

• You have been wondering: if this is a ‘team sport’, what sport is it?
• This is a terrible metaphor. But think about it.

The bottom line, actually

1. Communicate
2. Help each other
3. Be kind

• The features of GitHub should help you do the things you should already be doing.
• I am the guy falling over, the stones are tasks, my team mates are picking me up and dusting me off.
• What has your team been doing? What works for you?