A Guide to Contributing to an Open Source Project :A Contributor’s Journey

Contributing to open source projects is a rewarding way to improve your skills and collaborate with a community of developers.

I’ve been contributing to an open-source project for a while now and I’ve learned a lot during this journey. Contributing to a project with unfamiliar tools and being exposed to different techniques and coding styles has been a valuable learning experience for me.

It’s been a real eye-opener to contribute to a project owner who provides feedback, making it the closest experience I’ve had to working in a real team on a real project.

In this technical guide, we’ll walk through the steps of how to fork, clone, sync with the upstream repository, create branches for contributions, and submit pull requests (PRs).

Before diving into contributions, it’s crucial to understand the structure of the project. Familiarize yourself with the codebase, directory structure, and key components of the project.

Follow the project’s coding rules and standards. Write code that is clean, well-documented, and easy to maintain, so your contributions fit seamlessly into the existing codebase. Use code formatters like Prettier.

1. Forking the Repository

The first step is to fork the repository of the open source project you want to contribute to. Click the “Fork” button on the project’s GitHub page to create a copy of the repository under your GitHub account.

2. Cloning the Repository

After forking, clone the forked repository to your local machine using Git. Open your terminal and use the following command:

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

Replace your-username with your GitHub username and repository-name with the name of the repository you forked.

3. Syncing with the Upstream Repository

Navigate to your local repository directory in the terminal and run:

git remote -v

The git remote -v command displays a list of remote repositories connected to the current local repository in Git. The output of this command shows the URL and the name of each remote repository.

origin  https://github.com/username/project.git (fetch)
origin  https://github.com/username/project.git (push)

To keep your forked repository synced with the original (upstream) repository (the original repo url you forked), add the upstream repository as a remote.

git remote add upstream https://github.com/original-owner/repository-name.git

To verify the new upstream repository you have specified for your fork, type git remote -v again. You should see the URL for your fork as origin, and the URL for the upstream repository as upstream.

origin  https://github.com/username/project.git (fetch)
origin  https://github.com/username/project.git (push)
upstream  https://github.com/original-owner/repository-name.git (fetch)
upstream  https://github.com/original-owner/repository-name.git (push)

Next, fetch the changes from the upstream repository to your local repository. This step ensures that you have the latest updates without merging them into your branches yet. Use the following command:

git fetch upstream

After fetching the changes, you can merge them into your local branches. If you want to update the main branch, switch to it first.

git checkout main

Then, merge the changes from the upstream main branch into your main branch:

git merge upstream/main

Syncing your fork only updates your local copy of the repository. To update your fork on GitHub.com, you must push your changes.

Tip:In this step, git will ask you to provide a descriptive commit message explaining why this merge is necessary. If you are not able to submit your message, it is probably because of the git default editor(vi/vim).Please checkout here: https://stackoverflow.com/questions/19085807/please-enter-a-commit-message-to-explain-why-this-merge-is-necessary-especially

Finally, push the changes from your local main branch to your forked repository on GitHub:

git push origin main

By following these steps, you can sync your forked repository with the upstream repository, ensuring that your local copy is up to date with the latest changes.

4. Creating a Branch for Contributions

Before making changes, create a new branch for your contributions. Use a descriptive name for the branch that reflects the purpose of your changes:

git checkout -b my-first-contribution

Replace my-first-contibution with a relevant name for your branch.

5. Making Changes and Pushing to Your Fork

Make your changes to the codebase using your preferred code editor. After making changes, stage and commit them locally:

git add .
git commit -m "Description of your changes"

Then, push your changes to your forked repository on GitHub:

git push origin my-first-contribution

6. Creating a pull request from a fork

Once your changes are pushed to your forked repository, go to the GitHub page of your fork. GitHub will detect the new branch and give you the option to create a pull request. Provide a clear title and description for your pull request, then submit it for review by the project maintainers.

Change your repository branch from main to my-first-contribution(branch you made changes)

Always review your own pull request first to catch any mistakes you may have made. This ensures that project owners don’t waste time identifying and fixing errors.These kinds of attitudes will set you apart from others

Tips

It is generally recommended to work on a new branch whenever you make a new development. You can delete the branch after the project owner approve your pull request and merge your commits into the original repo.

It’s important to keep the main branch of your forked project synced with the upstream repository.

After creating a pull request (PR), subsequent commits on the same branch will automatically be included in the corresponding PR. This means that with each new commit, the PR will be automatically updated, and the added changes will be reviewed by the project’s maintainer.

Therefore, you don’t necessarily need to create a new PR every time you make a new commit on the same branch. The PR will reflect the latest state of the branch automatically.

Conclusion

By following these technical steps, you can contribute effectively to open source projects on GitHub. Regularly syncing with the upstream repository, creating branches for each contribution, and submitting pull requests will help you collaborate with the project’s community and make meaningful contributions to the codebase.

You can ask the project owner to make regular contributions to the project by collaborating with him/her. This offers opportunities beyond solo projects, like team collaboration, roles in larger projects, and getting feedback.

Creating a pull request from a fork - GitHub Docs

Fork a repository - GitHub Docs

Syncing a fork - GitHub Docs