Git Basics: Make your first open source contribution!

Prerequisite: Roles in Open Source

To understand all the terms described here, check out my other blog here.

• Repository maintainers: An open source project is hosted in a repository, in a platform like Github. Typically, the repository is maintained by one or multiple people, called maintainers. These are typically the people who have full rights to commit code to the main/master branch of the repository. Not only that, they can also manage & administrate the repository in general.

• Contributors: These are the people I intend to target in this blog post. They can have a look at all the code in the repository & all current issues with it. In turn, if they can improve upon it in some way, shape or form, they can create a pull request & do it that way. However, as with everything else, some steps need to be followed to ensure that your contributions get merged as smoothly as possible.

Now that you've understood who does what and where you fit in, let's get to the main topic.

Objective

Here, I'll be using one of my repositories to demonstrate this. I'll be contributing to my repository, as a contributor. Here, it'll be assumed that I don't have write access to the repository I'm trying to contribute to.

Steps to follow

STEP 0: Problem statement

Imagine you're browsing through my cheat-sheets repository on GitHub. You find a mistake under the Markdown section of the repository.

STEP 1: Clone the project onto your local system.

Now that you've found the error, it's time to look at the code. While you can directly see the code by clicking on Raw on the website, it's not the recommended way to do things when you want to contribute. Instead, these are the steps you need to follow:

• Ensure you have git installed on your local system. If it isn't, you need to get it first.

  • Windows: Download & install git from here.

  • Linux: Git is preinstalled in most cases. If it isn't, follow these steps.

      apt install git                # Debian based distributions
      pacman -S git                  # Arch Linux based distributions
      dnf install git                # RHEL based distributions
    

• Fork the repository to your Github account, using the button available on the main page of the repository.

• Navigate to the directory where you want to store the code.

Clone the repository using this command (insert your username). You can get the exact URI from your forked repository page:

[1 | code] git clone https://github.com/$YOUR_USERNAME/cheat-sheets.git
Cloning into 'cheat-sheets'...
remote: Enumerating objects: 31, done.
remote: Counting objects: 100% (31/31), done.
remote: Compressing objects: 100% (25/25), done.
remote: Total 31 (delta 10), reused 23 (delta 5), pack-reused 0
Receiving objects: 100% (31/31), 541.10 KiB | 1.78 MiB/s, done.
Resolving deltas: 100% (10/10), done.
[2 | code] $ cd cheat-sheets/
[3 | cheat-sheets] $ ls
GitHub.md  Markdown.md  README.md  res

STEP 2: Make changes in your cloned copy of the repository.

Once you clone the repository, you can see all the code in the current state. Also, git keeps track of all changes you make further. So now it's time to make some changes! In my case, I'll use Visual Studio Code to do it.

STEP 3: Push the changes to your branch.

Once you've done what you need to do, it's time to push your changes to GitHub. This is an intermediate step that pushes all changes you make to your forked copy of the repository, and not the original repository.

STEP 3.1: Create a new branch

In Github, every change you make must reside in a particular branch. You need to push similar types of changes or changes that aim to solve a single issue, in a specific branch. In this case, you need to create your branch in your forked copy and then push your changes to it.

[4 | cheat-sheets] $ git branch changes    # Create a new branch
[5 | cheat-sheets] $ git checkout changes  # [Optional] Push changes to the newly created branch by default.
M       Markdown.md
Switched to branch 'changes'
[6 | cheat-sheets] $ git branch -l         # List all branches. `*` denotes the active branch.
* changes
  main

STEP 3.2: Push the changes to the branch

This part happens in 3 steps:

• First, add all files you want to push, using git add.

• Next, you commit the changes with a commit message. Make sure the message is relevant to the changes you want to make.

• Finally, push the changes.

[7 | cheat-sheets] $ git add Markdown.md                                    # Add the changed files
[8 | cheat-sheets] $ git commit -m 'FIX: Corrected errors on line 44,45'    # Commit changes
[changes b5e729c] FIX: Corrected errors on line 44,45
 1 file changed, 2 insertions(+), 2 deletions(-)
[9 | cheat-sheets] $ git push origin changes                                # Push your changes
Enumerating objects: 5, done.
...
To https://github.com/sayande717/cheat-sheets.git
 * [new branch]      changes -> changes

STEP 4: Create a Pull Request for the changes.

The purpose of a pull request is to tell the maintainers that you have some changes made in your forked copy, which you want to push to the main repository.

To ensure that your pull request is in the proper format, make sure you read the repository's contributing guide. The guide is located in CONTRIBUTING.md in most cases**.**

Here what you need to do:

• First, note the ID of the issue you want to fix (check the Issues tab for that). If the issue isn't listed, create one.

• Next, go to the Pull Requests tab and click on Compare & pull request in the dialog that appears.

  

• Lastly, create the pull request. Make sure you link the issue to let the maintainers know which issue you're trying to fix. Just start typing the issue ID (#1 in this case) and it'll show up.

  

That's it! Now that you've notified the maintainers of your changes, they will review the code and then merge it if everything's fine! They may also ask for you to make further changes if something's not right. Make sure you keep up with that.

Note: In case you need to change the code again, make sure you push all new changes to the same branch you created. That way, all your changes will be in one place and under the same pull request.

STEP 5 (for the maintainer): Merge the pull request

The last step is taken by a project maintainer. After reviewing your changes, they are going to merge them with the main repository. In this case, the pull request will be merged with the main branch of my repository. Once that's done, you will see the status change from Open to Merged in the Pull Request discussions page.

Once your pull request is merged, you can also delete your branch and the forked copy of the repository if you don't intend to make further changes to it in the future.

Conclusion

Git & GitHub together provide a robust platform for both contributors and project maintainers. The process may seem a little complex & tedious at first, but you will understand the necessity of doing all this as you keep making more and more contributions. You can also possibly become a project maintainer yourself in the future! Happy learning & contributing :)