GitHub Group Projects Guide

Introduction

So, you want to work on a project on GitHub, but want to do it as a group. Here are some workflows for different scenarios. Whether you are contributing to an existing repository or creating a new repository makes a big difference in how you should go about things.

In every case, communication is key, make sure all group members are clear on what they are working on, otherwise you risk overwriting other peole’s code or creating conflicts. It is also important to make commit messages that clearly describe the changes that were made and pull request messages that describe the changes as well.

Creating a New Repository as a Group Project

If you are creating a new repository, you can choose one of the workflows below:

Simpler, Less GitHub Practice

1. Designate one group member to be the “Repository Manager”
2. Repository Manager creates a new repository for the project.
3. Other group members communicate additions and edits to the repository to the Manager through means outside GitHub (Google Docs, emails, text messages, etc.).
4. Repository Manager makes these changes as commits.
5. Other group members review these commits by looking at the repository, either by looking at the code or looking at the GitHub pages site.
6. Work continues until everyone is happy with the repository.

More Complicated, More GitHub Practice

1. Designate one group member to create/initialize the repository. We’ll call this person the “Repository Manager”
2. The other group members each fork the repository.
3. The other group members each create a branch within their fork. Name your branch with either the improvement you’ll be working on or with your first name. The other group members will keep their forks up to date with the original (upstream) respoitory by synching and always getting the latest changes before starting any new work.
4. All group members will coordinate who is responsible for which section or which new file so that conflicts or overwrites don’t occur.
5. When contributing their part, other group members will make commits to their branch of the fork.
6. When they are ready, group members will submit a pull request to the original repository. It’s best to stagger pull requests to avoid conflicts. The Repository Manager will examine the pull requests and approve the ones that are ok and ask for changes for ones that are not. The Repository Manager then merges pull requests into their repository. After each pull request is merged into the original repsitory, each group member should update their fork.

Warning: Group members should try not to work on the same sections of files, this can cause conflicts within Git that it may not be able to resolve.

Note: If the project uses GitHub Pages, make sure the settings for pages are displaying the correct fork and branch so you can actually see your changes as you make them.

Contributing to an Existing Repository as a Group Project

There are several possible workflows for doing this. Before starting work, you’ll want to look at the existing project’s guidelines for contribution. For example, the guidelines for the FFmprovisr project.

Simpler, Less GitHub Practice

1. Designate one group member as the “Repository Manager”
2. Repository Manager forks the existing repository and creates a new branch. It is best practice to create a new branch when contributing to an existing project.
3. Manager keeps their fork up to date with the original (upstream) repository by synching with it before any new work is started.
4. Other group members communicate additions and edits to the repository to the Manager through means outside GitHub (Google Docs, emails, text messages, etc.).
5. Repository Manager makes these changes as commits in their branch of their fork.
6. Other group members review these commits by looking at the code or GitHub pages of the fork.
7. Work continues until everyone is happy with the changes.
8. When the changes are ready, the repository manager submits a pull request to the original (upstream) repository.

More Complicated, More GitHub Practice

1. Each member of the group forks the original repository.
2. Each group member creates a branch within their fork. They should name the branch with their first name.
3. Each group member makes sure to update their branch with the latest changes before they start new work.
4. All group members will coordinate who is responsible for which section or which new file so that conflicts or overwrites don’t occur. For example, if creating new files, only one group member at a time should be assigned to work on a new file added to the repository.
5. Each group member works on their branch separately, making commits as they need to. This will work fine if the group is only working on existing files within the respoistory. Group members should try not to work on the same sections of files, this can cause conflicts within Git that it may not be able to resolve.
6. When each group member is satisfied with their contribution, they make a pull request to the original repository. This will result in multiple pull requests for the repository. Ideally these Pull Requests would be staggered to give the maintainers time to review them and merge them into the original repository.

Warning: Group members should try not to work on the same sections of files, this can cause conflicts within Git that it may not be able to resolve.

Note: If the project uses GitHub Pages, make sure the settings for pages are displaying the correct fork and branch so you can actually see your changes as you make them.

See more information on pulling changes from a pull request into your fork

Further Reading

GitHub Guide to Contributing to Open Source - has some helpful info but instructions use command line for Git.