Exercise notebook: Git collaborating
-blue){kind=icon}
The notebook builds on our peer-reviewed pedagogical foundations.
We 
your feedback and suggestions on this notebook!
With this notebook, we practice collaborating with Git in small groups.
| Practice | Label | Time (min) |
|---|---|---|
| 1 | Work in a shared repository | 5 |
| 2 | Work in a fork | 13 |
| 3 | Wrap-up | 2 |
| Overall | 20 |
We are here to help if errors or questions come up!
Form small groups of 3-5 students and solve the following tasks together.
Part 1: Work in a shared repository
In the first part, we will create a simple shared repository setup. Every team member will have access to the same repository, committing directly to main, or creating branches and pull-requests. We will not download the repository, but edit the files directly on GitHub instead.
Task: Select one maintainer, who creates a new remote repository on GitHub and invites the other team members as contributors. You can work on a public or private repository. In addition, the maintainer creates a README.md file, choosing a project name and creating a contributor section similar to the following:
README.md
Task: Next, each team member edits the README.md directly on GitHub (on the main branch), adding her/his name.
After creating the README.md, the team decides to add more contents, working in parallel branches, and using pull-requests to discuss and integrate the changes.
Task Contributor A: Create a branch license, adding the MIT License in a file named LICENCSE.
Task Contributor B: Create a branch contributing, adding the contributing guidelines in a file named CONTRIBUTING.md.
Task Contributor C: Create a branch code_of_conduct, adding the code of conduct in a file named CODE_OF_CONDUCT.md.
Afterwards, each contributor opens a pull-request to integrate the changes. Review each other's changes, add a commend to confirm whether the changes are adequate and merge them using the rebase option.
Part 2: Work in a fork
In this part, we work with a fork of an existing project. The CoLRev repository serves as the upstream/origin. Your group creates a fork and edits the data on Codespaces (or a local repository).
| Term | Definition |
|---|---|
| remote/origin | origin is the default name Git gives to the remote repository when it's cloned. It typically refers to the source repository from which your local repository is cloned. |
| upstream | upstream refers to the primary repository from which a fork is created. It is the main project that your local or forked repository is tracking. |
| fork | A fork is a copy of a repository that is created under a different user's account. It allows you to freely experiment with changes without affecting the original repository. |
Step 1: Maintainer Forks the Project: The maintainer forks the CoLRev repository, creating their own copy of the project. They invite contributors to collaborate on this fork.
Step 2: Contributors Open the Project in Codespaces: Contributors open the maintainer's forked repository in GitHub Codespaces. This action effectively clones the remote repository to a development environment. Contributors can now work on this forked version directly.
Step 3: Implement Changes on Branches Contributors create new branches in Codespaces to implement changes. Branching ensures that any new features or bug fixes are isolated from the main codebase until they are fully tested and reviewed.
Step 4: Push Changes and Open a Pull Request: Once changes are implemented, contributors push their branch to the remote repository (the fork). After pushing, contributors open a pull request (PR) to propose that the maintainer review and merge their changes into the fork's main branch.
Step 5: Maintainer Merges Changes to the Fork: The maintainer reviews the pull requests, and if everything looks good, merges the changes into the forked repository's main branch. The fork is now updated with the new contributions.
Step 6: Synchronize Codespaces with the Main Branch: After the maintainer merges changes, contributors need to sync their Codespace environment with the latest version of the fork's main branch. This ensures that they are working with the most up-to-date version of the project.
Step 7: Maintainer Opens Pull Request to Original Repository: Once the fork has accumulated significant changes, the maintainer opens a pull request from the fork to the original CoLRev repository, proposing that the updates in the fork be integrated into the main project. After review, the pull request is either merged or closed. ## Wrap-up 🎉🎈 You have completed the Git collaborating notebook - good work! 🎈🎉 In this notebook, we have learned about - The role of remote repositories and forks - The synchronization using `git pull`, `git push`, and **pull requests** - The different permissions when working in a shared repository or contributing through forks.