Featured image of post Project Collaboration Development Process on GitHub/GitLab
Development

Project Collaboration Development Process on GitHub/GitLab

The process of collaborating with others to develop projects on GitHub or GitLab

Background

If you see an interesting project on GitHub and want to participate in its development, you generally need to follow a certain process. Here’s a general project collaboration development process.

Of course, this process is not only applicable to GitHub, but also to other code hosting platforms such as GitLab.

Prerequisites

  • Git is installed
  • GitHub account is registered

Git settings

  1. Set username and email

    There are two modes for setting the username and email.

    • If you only use one GitHub account, you can set the global username and email.

      1
2

      git config --global user.name "Your Name"
git config --global user.email "Your Email"

    • If you have multiple GitHub accounts, you can set the username and email for each Git repository separately.

      1
2
3

      cd /path/to/your/repo
git config user.name "Your Name"
git config user.email "Your Email"

  2. Login credential management

    After setting the username and email in the previous step, when cloning a repository and every time you git push, you need to enter your GitHub username and password, which is very cumbersome. You can use a credential manager to save your username and password.

    • Windows

      If the version number of Git you installed is higher than 2.29, Git has integrated support for GitHub OAuth. When you first clone a GitHub private repository via HTTPS, Git will prompt you to log in to GitHub using a browser and authorize Git to access your GitHub account. After that, Git will automatically save your GitHub credentials, so you don’t need to enter your username and password again.

    • macOS

      • Method 1 (Old method):

        You need to install Git Credential Manager. You can run the following command in the terminal:

        1

        brew install --cask git-credential-manager

        After installation, when you first clone a GitHub private repository via HTTPS, Git will prompt you to log in to GitHub using a browser and authorize Git to access your GitHub account. After that, Git will automatically save your GitHub credentials, so you don’t need to enter your username and password again.

        Git Credential Manager supports various Git hosting platforms, including GitHub, GitLab, Bitbucket, etc., and you can use this tool for credential management.

      • Method 2 (Recommended method):

        For GitHub accounts, you can use the GitHub CLI tool for credential management. You can run the following command in the terminal to install the GitHub CLI tool:

        1

        brew install gh

        After installation, run the following command to log in to your GitHub account:

        1

        gh auth login

        Follow the prompts to log in to your GitHub account via a browser. After a successful login, the GitHub CLI tool will automatically configure Git’s credential management, so you don’t need to enter your username and password again.

    • Linux

      Linux systems are similar to macOS and can choose either Git Credential Manager or GitHub CLI tool for credential management. Just use the package manager of your Linux distribution to install it.

GitHub collaboration development process

Overview

To participate in the development of others’ projects, the general idea is:

  1. Fork the project to your own GitHub account on the GitHub website.
  2. Clone the forked project to your local machine and add the original repository as a remote repository. This way:
    • Your local repository corresponds to two remote repositories: one is the Fork repository (origin), and the other is the original repository (upstream).
    • Do not modify the main branch of the origin remote repository on GitHub, and do not develop on the main branch locally. Always keep the local main branch, the main branch of the origin remote repository, and the main branch of the upstream remote repository in sync.
    • When you want to add a new feature or fix a bug, first create a new branch from the main branch and develop on this new branch.
  3. After completing development locally, push the new local branch to the origin remote repository. GitHub will remind you x commits ahead of upstream/main, y commits behind upstream/main, where x represents the number of commits on your new branch, and y represents the number of new commits on the main branch of the upstream remote repository while you were developing the new feature/fixing the bug.
  4. If y is not 0, it means the main branch of the upstream remote repository has new commits, and you need to synchronize your new branch with the main branch of the upstream remote repository.
    • First, pull the latest code of the main branch of the upstream remote repository to the local main branch.
    • Then merge the local main branch into your new branch. This process has two cases:
      • If there are no conflicts, you can directly merge or rebase.
      • If there are conflicts, you need to resolve these conflicts and then commit.
  5. If you want to merge your new feature/bug fix into the original repository, you need to create a Pull Request on GitHub, wait for the author of the original repository to review your Pull Request, and if necessary, you need to make changes according to the feedback from the author of the original repository.

Below we will introduce this process in detail.

Operations on the GitHub website —— Fork

  1. Open the GitHub page of the project you want to participate in, click the Fork button in the upper right corner, and fork the project to your own GitHub account. We call the original project the original repository and the project forked to your own account the Fork repository.

  2. In your GitHub account, find the forked project (i.e., Fork repository), click the Clone or download button, and copy the URL of the project.

Local operations —— Clone

  1. In the terminal on your local machine, switch to the directory where you want to store the project, and run the following command to clone the project to your local machine.

    1

    git clone https://github.com/your-username/project-name.git

    Here, your-username is your GitHub username, and project-name is the name of the project.

  2. Enter the project directory, run the following command to add the original repository as a remote repository.

    1

    git remote add upstream https://github.com/authors-usename/project-name.git

    Here, authors-username is the GitHub username of the author of the original repository, and project-name is the name of the project.

    Then run the following command to check the status of the remote repository.

    1

    git remote -v

    If everything is normal, you will see output similar to the following:

    1
2
3
4

    origin https://github.com/your-username/project-name.git (fetch)
origin https://github.com/your-username/project-name.git (push)
upstream https://github.com/authors-username/project-name.git (fetch)
upstream https://github.com/authors-username/project-name.git (push)

    Here, origin is your Fork repository, and upstream is the original repository.

Local development

  1. In the terminal on your local machine, switch to the project directory, run the following command to create a new branch.

    1

    git checkout -b new-branch-name

    Here, new-branch-name is the name of your new branch, which can be the name of the new feature you want to add, or the name of the bug you want to fix.

  2. In the terminal on your local machine, develop, modify code/add new features/fix bugs. Then run the following command to add the modified files to the staging area and commit them to the local repository.

    1
2

    git add .
git commit -m "Your commit message"

    You can also push the changes in the local repository to the Fork repository.

    1

    git push origin new-branch-name

  3. Repeat the operations in step 2 until your new feature/bug fix is complete.

  4. On GitHub, open your Fork repository. GitHub will remind you x commits ahead of upstream/main, y commits behind upstream/main, where x represents the number of commits on your new branch, and y represents the number of new commits on the main branch of the upstream remote repository while you were developing the new feature/fixing the bug. If y is not 0, it means the main branch of the upstream remote repository has new commits, and you need to synchronize your new branch with the main branch of the upstream remote repository.

    1
2

    git checkout main
git pull upstream main

    Then you can merge the latest code of the main branch into your new-branch-name branch locally. There are two ways to do this “merge”: merge and rebase:

    • merge: Merge the latest code of the main branch into the new-branch-name branch, the commit history of the new-branch-name branch remains unchanged, forming a new commit history.

      1
2

      git checkout new-branch-name
git merge main

    • rebase: Will package the commit history of the new-branch-name branch and place it after the latest commit history of the main branch, forming a new commit history.

      1
2

      git checkout new-branch-name
git rebase main

    Whether merge or rebase, if the main branch of the original repository has modified the files you modified on the new-branch-name branch, conflicts will occur. You need to resolve these conflicts. After resolving the conflicts, run the following command to add the modified files to the staging area and commit them to the local repository.

    1
2

    git add .
git commit -m "Your commit message"

    Finally, run the following command again to push the modified files to the Fork repository.

    1

    git push origin new-branch-name

    This way, your new-branch-name branch will not have conflicts when merged into the main branch of the original repository.

Operations on the GitHub website —— Pull Request

  1. Before creating a Pull Request, first switch to your new-branch-name branch on GitHub and confirm that the y in This branch is x commits ahead of upstream/main, y commits behind upstream/main displayed on GitHub is 0 (i.e., only shows This branch is x commits ahead of upstream/main, not showing behind), indicating that your new-branch-name branch is already synchronized with the main branch of the original repository. If y is not 0, return to the previous step, step 4, and first synchronize your new-branch-name branch with the main branch of the original repository.

  2. Open the GitHub page of your Fork repository, click the New pull request button, and create a new Pull Request. Note that if the original repository provides a Pull Request template, you need to fill in the title and content of the Pull Request according to the Pull Request template of the original repository.

  3. Wait for the author of the original repository to review your Pull Request. If necessary, you need to make changes according to the feedback from the author of the original repository.

  4. If the author of the original repository accepts your Pull Request, congratulations, your code will be merged into the original repository.

Local operations —— Update local repository

  1. In the terminal on your local machine, switch to the main branch, run the following command to pull the latest code of the main branch of the original repository to your local machine.

    1
2

    git checkout main
git pull upstream main

    You can also use the git fetch upstream main command to check the latest code of the main branch of the original repository, and then use the git merge upstream/main command to merge the latest code of the main branch of the original repository into the main branch of your local machine.

    1
2
3

    git fetch upstream main
git checkout main
git merge upstream/main

    This way, your local main branch will be synchronized with the main branch of the original repository.

  2. Then you can push the main branch of your local machine to the Fork repository.

    1

    git push origin main

  3. (Optional) If your new-branch-name branch has been merged into the main branch of the original repository, you can delete the new-branch-name branch.

    1

    git branch -d new-branch-name

    You can also delete the remote branch of the new-branch-name branch.

    1

    git push origin --delete new-branch-name

This way, you have completed the work of collaborating with others to add a new feature/fix a bug on GitHub.

Continue to Develop New Features/Fix New Bugs

If you need to continue adding new features/fixing new bugs, you can first synchronize your main branch of the Fork repository with the main branch of the original repository to ensure that you start working from the latest version of the project:

```bash
git checkout main
git pull upstream main
git push origin main
```

Then, you can create a new branch on the main branch to continue developing new features/fixing new bugs.

```bash
git checkout -b another-new-branch-name
```

The subsequent operations are the same as after local development.

comments powered by Disqus