Collaborating with Your Team

Last updated on 2023-07-17 | Edit this page

Overview

Questions

How can I use GitHub to manage a lesson development project?
What communication channels are effective for a lesson development team?
What strategies exist to help collaborators make decisions and govern an open source project?

Objectives

After completing this episode, participants should be able to…

Report and track issues with the GitHub interface.
Review and provide feedback on contributions from collaborators.
Prepare for a decision-making meeting between collaborators.

In this episode we expand on how to use GitHub effectively among a group of known collaborators on an open source lesson development project, setting the stage for introducing tools and practices for working with newcomers. Here, we explore GitHub features to help you keep track of what needs doing on the lesson, making decisions and managing your project. Collaboration skills covered in this lesson are transferable to any similar open source project you may be involved with.

Managing Issues

Issues are GitHub’s framework for managing issue/bug reports, feature requests, and lists of future work. They provide a single shared record of all the problems people have found with the lesson, and improvements that could be made, along with solutions and discussions around them. This helps the team to keep track of what they need to work on later, and reduces the chance of receiving redundant reports of issues you already know about.

When you create an issue, you can add a range of details to it. An issue can be assigned to a specific team member - this can be a helpful way to know who is currently working to fix an issue or a way to assign responsibility to someone to deal with it. You can assign one or more labels to issues to classify or group them. Labels can also be given colours, allowing you to see at a glance from the Issues page the state of your project. The default labels available in GitHub include:

bug - indicates an unexpected problem or unintended behavior
documentation - indicates a need for improvements or additions to documentation
duplicate - indicates similar or already reported issues, pull requests, or discussions
enhancement - indicates new feature requests, or if they are created by a lesson maintainer, indicate planned new features
good first issue - indicates a good issue for first-time contributors
help wanted - indicates that a maintainer wants help on an issue or pull request
invalid - indicates that an issue, pull request, or discussion is no longer relevant
question - indicates that an issue, pull request, or discussion needs more information
wontfix - indicates that work won’t continue on an issue, pull request, or discussion

Check the GitHub documentaiton on Issues for the full reference. You can also create your own custom labels to help with classifying issues. There are no rules really about naming the labels - use whatever makes sense for your project. Some conventional custom labels include: status:in progress (to indicate that someone started working on the issue), status:blocked (to indicate that the progress on addressing the issue is blocked by another issue or activity), etc.

Exercise: creating issues (15 minutes)

After your trial run, you should have created a list of issues you identified with your lesson. Open issues on the GitHub repository for your lesson, for each item on that list. Remember to add labels to each issue according to its type, priority, etc. As you create them, you may also want to assign these issues to a member of your lesson development team.

Managing Contributions - Pull Requests

Although it is possible (for collaborators with sufficient access to the project) to make changes to a lesson directly on the main branch of the repository, doing so is not recommended:

It increases the likelihood of unintentional conflicts being created when two collaborators work on the same file simultaneously.
It does not provide an opportunity for changes to be checked and discussed before they are included in the lesson. This makes it much more likely that mistakes will be included in the lesson, and that the commit history of the project will include many changes made only to fix/polish/undo previous commits.
It prevents your team from benefiting from the powerful features that Git and GitHub provide to support and foster collaboration.

Instead, it is recommended practice to do most work in branches: sets of changes that build on the work in the main branch (or another) but are not included in that branch until they are explicitly merged into it. GitHub provides a way for this merging process to be managed, by giving a platform for the changes to be described, discussed and reviewed, before a decision is made to integrate or not integrate the changes in the default branch of the project and the associated lesson.

On GitHub, these units of discussion, review, and acceptance/rejection of the changes within a branch are called Pull Requests.

Why “Pull Request”?

The term Pull Request originates from the early days of GitHub, when a contributor would be requesting that the project maintainer(s) use Git to fetch (download) their branch and merge the changes into the main branch of the project. In the terminlogy of Git, this combination of fetching and merging a set of changes is called pulling. The name Pull Request is slightly anachronistic now, because a project maintainer can often manage the whole process of reviewing a contribution in GitHub’s web interface.

Note: A common nickname for a Pull Request is PR or PRs for Pull Requests.

Protecting `main`

As the maintainer of a project, you can enforce this workflow by protecting the default branch of the GitHub repository: this will prevent anyone without Admin access from committing changes directly to that branch.

To activate this branch protection:

Open the Settings tab of the repository and select Branches in the left sidebar, under the Code and automation section.
Click the “Add branch protection rule” button.
Type the name of the branch your GitHub Pages are being built from (main) into the “Branch name pattern” box.
Check the “Require a pull request before merging” option, but leave the others unchecked for now because we don’t need them for this project.

Submitting and Reviewing Pull Requests

The Trainers will collaborate on a demonstration of the process laid out below.

Pull Request Activity

Note: This activity is designed to be carried out by two Trainers acting in two different roles: “(S)” denotes the Pull Request Submitter role, “(R)” the Pull Request Reviewer.

(S) Explore list of issues on repository, choose issue to fix, make note of issue number.
(S) Edit a file to fix the issue, commit changes to a new branch with an appropriate name. Ensure that the changes include some typo etc that the Reviewer will be able to comment on and/or suggest a fix/improvement to.
(S) Show how to open a pull request from that new branch to main.
(S) In Pull Request description, reference the number of the issue being fixed, using a keyword “Fixes #X” or “Resolves #X” (where X is the issue number) to ensure automatic closure.
(S) Demonstrate how to mark the PR as a draft, and then how to mark as it as ready for review.
(S) Request a review from the Pull Request Reviewer.
(R) Open the new Pull Request in GitHub.
(R) Explore the diff of the PR, by opening the Files changed tab and talking through the display.
(R) Comment on a line in the diff.
(R) Suggest a change to the diff, using the “Add suggestion” button or three backticks marked suggestion.
(R) Complete your review by adding some summary text and selecting “Request changes”.
(R) Return to Conversation tab, to show how the PR thread looks after the review has been submitted.
(S) Navigate to PR and the Files changed tab.
(S) Respond to Reviewer’s comment(s), accept their suggested changes (draw attention to the option to batch multiple suggestions into a single commit).
(S) Return to the Conversation tab and request a new review from the Reviewer.
(R) Look again at the PR diff (Files changed) and ensure that requested changes have been made.
(R) Approve the PR.
(R) Thank the Submitter for their contribution.
(R) Merge the PR.
(R) Navigate to issue listing to confirm that the relevant issue has been automatically closed.

Practice with Pull Requests (15 minutes)

In breakout groups, assign yourselves the role of Submitter (S) and Reviewer (R), and repeat the process described above by completing the steps below. If there are any issues open on the repository that can be solved very quickly, feel free to address those with this exercise. Otherwise, the Submitter can open a Pull Request to make simple changes: typo fixes, or some completely arbitrary changes to a file. If the changes made for the exercise are not improvements to the lesson, the Reviewer should follow all the steps but close the PR at the end instead of merging it.

(S) Edit a file and commit the changes to a new branch.
(S) Open a new Pull Request from this new branch to main. If your PR will fix an open issue on your repository, include “Fixes #X” at the start of the PR description, where X is the issue number.
(S) Request a review from the Reviewer.
(R) Review the PR, making comments and suggesting changes as appropriate. When you have finished, approve the PR or request changes, based on your review.
(S) Respond to any comments from the Reviewer and/or, if any changes were requested, make those and re-request a review when you have finished.
(R) When all changes have been made to your satisfaction, approve the PR, thank the Submitter for their contribution, and merge the PR (Or close it if the changes were made for practice but should not be included in the actual lesson.)

Managing Communication

Having an open, publicly-visible list of all the issues with your project is a helpful way of letting people know you are aware of issues and you are working on them. This can indicate to an external audience that the project is active. It also provides you and your collaborators with an “at a glance” view of the state of the project, making it easier to prioritise future work.

GitHub provides a useful notification feature for collaborative work - mentions. The mention system notifies team members when somebody else references them in an issue, comment or pull request - you can use this to notify people when you want to check a detail with them, or let them know something has been fixed or changed (much easier than writing out all the same information again in an email!). You can use the mention system to link to individual GitHub accounts or whole teams for mentioning multiple people. Typing @ in GitHub will bring up a list of all accounts and teams linked to the repository that can be “mentioned”.

Slack is commonly used in the Carpentries community for quick, day-to-day message exchange among teams. You can create your own Slack workspace for free or create a channel for your lesson development project under the Carpentries public Slack workspace. Note that the Carpentries Slack is an enterprise workspace so all messages and files will be retained and no messages will be lost (for free workspaces only the most recent 10,000 messages can be viewed and searched and file storage limit is 5 GB).

Collaborators can also use other platforms to discuss lesson development or receive contributions from newcomers who are not yet fluent in using GitHub’s systems of communication. The Carpentries can assist with creating a mailing list specific to the development of your lesson on their TopicBox platform for managing threaded email discussions. Also make sure to join the Incubator lesson developers mailing list on TopicBox to keep an eye on announcements and discussions relating to lesson development in general within the Carpentries community.

Meeting minutes are a useful way of providing a permanent record of the purpose of a meeting and what was talked about, including any decisions made or actions taken, that can be referred back to for any follow-ups. Recording meeting minutes does not have to be hard - remember that you are part of a team and there are many platforms that allow collaborative note taking. The Carpentries provides CodiMD and Etherpad instances as two options for taking shared notes, widely used at workshops for sharing pieces of code, references and notes between instructors and learners. For some advice on holding effective meetings, see the Meetings, meetings, meetings section of Teaching Tech Together by Greg Wilson.

Project planning & management

Developing a lesson is a project and, like most projects, it consists of multiple tasks. Keeping track of the list of tasks the team has to do, progress on each, prioritising tasks for future development, sprints and releases, etc., quickly becomes a non-trivial task in itself. Without a good project management framework, it can be hard to keep track of what’s done, or what needs doing, and particularly difficult to convey that to others in the team or share the responsibilities.

GitHub provides two project management tools for this purpose - Milestones and Project Boards. Both Milestones and Project Boards implement an agile development/project management system to help you keep track of different components of the project and their current status. Milestones are good for scrum-style project development and management - i.e. time-bound, structured iterations and working in short sprints on batches of issues. Project Boards implement a Kanban methodology - good for managing continuous delivery and steady flow of work in a project.

Both Project Boards and Milestones are a way of organising issues into smaller “sub-projects” (i.e. smaller than the “project” represented by the whole repository). When should you use one over the other? Project Boards provide a way of visualising and organising the work on a higher level (e.g. more suitable for project management tasks that are not time-bound). Milestones are a way to organise lower-level tasks that have deadlines and progress of which needs to be closely tracked (e.g. release management). How you organise and partition your project work is up to you and the size of your project. For example, you could create a project per milestone or have several milestones in a single project, and split milestones into shorter sprints.

Milestones

A Milestone is a collection of issues to be worked on in a given time period. Milestones are good for tracking progress as they provide an ordered list of issues which must all be resolved for the overall task to be considered complete. Milestones work like labels - they mark and group issues that are expected to be closed at some point in time.

The Milestones page in GitHub is accessible from the Issues page - from there you can create a new milestone, see the percentage of issues completed for your milestones and their due dates. You can also sort milestones by due date and prioritise issues within a particular milestone. Back on the Issues page, you can assign issues to milestones and filter your issues by milestones.

Project Boards

A Project Board (or Kanban board, from the Japanese word for ‘card’) uses columns and cards to keep track of tasks - you break your project down into tasks which you write on cards, then move the cards between columns that describe the status of each task. Cards are usually small, descriptive and self-contained tasks that build on each other. Breaking a project down into clearly-defined tasks makes it a lot easier to manage and develop. GitHub project boards interact and integrate with the other features of the site such as issues and pull requests - cards can be added to track the progress of such tasks and automatically moved between columns based on their progress or status.

GitHub provides template boards that by default contain the three ‘basic’ columns, with pretty self-explanatory names:

To Do
In Progress
Done

If you add an issue or pull request to a card in the board, it will automatically be moved to ‘Done’ for you when you close the issue or merge the pull request. One common extra column is On hold or Waiting. If you have tasks that get held up by waiting on other people (e.g. to respond to your questions) then moving them to a separate column makes their current state clearer.

You can also create a card without an issue. Such cards (or notes) can have detailed content like checklists or ideas which are not necessarily suitable for inclusion in your issue tracker. However, GitHub also allows you to convert a card to an issue, should you wish to do so, so you can add labels or detailed comments to it. Sometimes, a card you thought was simple and self-contained might turn out to be a bigger task than you anticipated - in that case, it is sensible to create new cards that reference the one they broke off from.

Once your project board has a large number of cards on it, you might want to begin prioritising them. Not all tasks are going to be equally important, and some will require others to be completed before they can even be begun. Common methods of prioritisation include:

Vertical position: the vertical arrangement of cards in a column implicitly represents their importance. High-priority bugs go to the top of To Do, whilst tasks that depend on others go beneath them. This is the easiest one to implement, though you have to remember to correctly place cards when you add them.
Priority columns: instead of a single To Do column, you can have two or more, for example - To Do: Low Priority and To Do: High Priority. When adding a card, you pick which is the appropriate column for it. You can even add a Triage column for newly-added issues that you’ve not yet had time to classify. This format works well for project boards devoted to bugs.
Labels: if you convert each card into an issue, then you can label them with their priority - remember GitHub lets you create custom labels and set their colours. Label colours can provide a very visually clear indication of issue priority but require more administrative work on the project, as each card has to be an issue to be assigned a label. If you choose this route for issue prioritisation - be aware of accessibility issues for colour-blind people when picking colours.

Project Boards vs Milestones

For a good description of differences between the two, have a look at this answer on StackOverflow.

A Project Board answers the question:

“What are we working on at the moment?”

A Milestone answers the question:

“What is remaining to finish off this task?”

Exercise: prioritising issues & planning work (15 minutes)

Use Project Boards and/or Milestones to prioritise issues and plan the first sprint and/or the first lesson release with your team.

Depending on how many issues were registered on your repository, it is possible that you will not be able to work on all the issues in the first sprint. As the development of your lesson progresses, any remaining unresolved issues can be reconsidered and prioritised for another milestone and you can use a Project Board to plan them.

This process of receiving new issues and requirements, prioritisation, and working on them is naturally continuous - with the benefit that at key stages your team is repeatedly re-evaluating what is important and needs to be worked on which helps to ensure real concrete progress against project goals and requirements which may change over time.

Project Governance

In addition to managing your project on a day-to-day basis, you should consider a governance model for your lesson to describe the ground rules of participation, the roles that project participants can take on and the process for decision making within the project. You may wonder why you’d ever need a formal governance process - after all, everyone in your team is collegial, polite and hard-working. However, even among the most harmonious teams you will likely realise you need an agreed way to make decisions and resolve conflicts when your team encounters their first real disagreement.

The moment your collaborator group exceeds 3 or 4 members (and fewer if the collaborators do not all know each other equally well at the outset) you should establish and document some kind of governance process. It will help mitigate any power imbalances which are expressed when one team member (or a group of team members) are more vocal and are able to dominate the decision-making process. It is advised to make these considerations early on, before your project grows too much and introducing structure and process into it becomes more difficult and complicated. Besides, if you do not establish these processes from the start, you are likely to discover the need to do so only when you first encounter disagreement within the team: a situation unlikely to provide perfect conditions for a discussion of governance.

Here are some aspects of governing a project that you should consider. These are borrowed from the Working in teams chapter of Research Software Engineering with Python, a book on how to work productively in small teams where everyone is welcome:

For some other examples and inspirations of governance processes, consider the following:

Martha’s Rules for discussing and deciding on issues in group meetings (if you cannot access the publication, see Greg Wilson’s explanation of Martha’s rules)
GitHub’s Minimum Viable Governance (MVG) for establishing a lightweight governance process into free and open source projects that are run in version control systems. In MVG decisions are made through consensus of the project maintainers or determined based on the maintainers’ consideration of a number of factors in “good faith” (when explicit agreement of all maintainers cannot be reached). In reality, consensus-based governance can run you into trouble when you hit an issue where maintainers do not all agree but still want to make progress. Also, the definition of “good faith” is open to interpretation and leaves plenty of room for people, especially the powerful, to get away with acting in bad faith. A system based on voting and majorities may help you get around this issue. MVG is designed for a one organisation-many projects setup and is too elaborate for a single lesson project. However, it includes “boilerplate” template files for a steering committee, charter, governance, Code of Conduct documents, and language laying out a preference for consensus but with voting as a fallback, and other templates that may be helpful for those starting out and unsure about how to get on with establishing a governance process.
This list of resources related to community governance from The Center for Scientific Collaboration and Community Engagement provides a collection of links to further reading material on this topic. It includes various guides, blog posts, and examples of community governance that may inform the discussions and decisions for your project.

Exercises: decision making process (15 minutes)

As a team read Greg Wilson’s explanation of Martha’s rules on running decision making meetings.

Discuss with your colleagues if it would work for your team and if not - what would you propose. Write down any questions you may have for your trainers.

Keypoints

GitHub’s features Issues, Mentions and Project Boards can all be used to effectively communicate in a team of collaborators and manage a lesson development project.
Slack and emailing lists provide communication channels outside of GitHub - for quick day-to-day messaging and more permanent discussions around lesson issues and development, respectively.
Make sure to establish a governance model for your project early on - to describe the ground rules of participation and the process for decision making within the project.