This document serves as a brief primer on the different Git and GitHub workflows you can leverage to effectively run a project with more than one contributor. Our intent in creating this document is to create a resource that you can revisit every time you are involved in a collaborative project, from the inception of the project (repo setup, task assignment, etc.) to the intricacies of development (branching, merges, etc.). We leave out much of the esoteric nuances of Git, but we encourage you to research such things on your own.

1. What are Git & GitHub and how do they differ?
2. Using Git & GitHub for Team Collaboration
   1. Creating a project
      1. Create repo on GitHub / Direct Access
      2. Cloning with Git / Fork & PR
         1. Cloning Public Repo with HTTPS
         2. Cloning Private Repo with fine-grained personal access token
   2. Setting up the project
      1. Create .gitignore
      2. Use GitHub issues for task assignment & delegation
         1. (This is not something that you would ONLY do when you’re setting up a project, but I think it makes sense to start mentioning it here)
      3. Create a new branch
         1. Branching conventions
            1. main/ vs. dev/ vs. feat/* convention
               1. dev/ is often overkill, esp in MDST scenario, so it suffices to cover main branch vs. feat branches
   3. Development
      1. Merging branches
         1. Push to branch → Create GitHub PR → Link PRs to Issues → Close Issues & Merge work across branches in the remote repo
         2. Dealing with issues
            1. Merge conflicts
            2. Rollbacks
            3. Squashing commits
            4. Cherry picking commits
      2. GitHub code review of PRs
   4. Wrapping up project
      1. Creating a good README.md

What are Git & GitHub and how do they differ?

Git is a distributed version control system that tracks changes to files and coordinates work on those files among multiple people, allowing for collaboration as well. Internally, Git uses a combination of snapshots and differences (diffs) to keep track of changes in your project. When you make a ‘commit’, Git stores a snapshot of all the files in our project at that point in time (think of it as a save point).

By initializing a Git repository, you now have some storage space where your project files are kept along with their entire version history, allowing you to track changes, revert to previous states, and collaborate with others.

GitHub is a web-based platform that hosts Git repositories in the cloud. GitHub makes it easy for developers to collaborate on projects by sharing their Git repos online. Multiple people can contribute to a project, review each other’s code, and track issues. GitHub also offers additional features like GitHub Actions for CI/CD, GitHub Pages for hosting static websites, and GitHub Copilot for AI-assisted coding.

Using Git & GitHub for Team Collaboration

Creating a Project

In a collaborative development environment, GitHub provides two main methods for contributing to a project. One is Direct Access, and the other is Fork & PR.

Direct Access

With direct access, contributors are given permission to push changes directly to the repository. This method is typically used for smaller teams or when contributors are trusted collaborators.

Here are the steps to contribute to a repository using direct access, assuming permission is granted:

1. Clone the repository. This creates a local copy of a remote repository.
2. For any changes you want to make to the repository (aka contributions), you may choose to create a new branch for your work. This isn’t required, but is considered good practice to keep the ‘main’ branch clean from any errors or bugs. We’ll cover branches in a later section.
3. You can now make your changes and commit them.
4. Finally, you can simply push your changes to the remote repository because you have direct access to push contributions.