Tutorials

How to Fork and Contribute to a Project Using Git

September 24, 2018
Code Snippet displayed on a screen

This article walks you through the process of forking a project on GitHub, and it also shows you how to create a pull request so you can contribute your changes back to the original project.

Forking is a process where you copy a repository that is owned by someone else. When you fork you can make changes to projects that you do not own. Forking is most commonly used for three circumstances. You may contribute to a shared project, you propose source level changes, and forking allows you to start off with a shared code base, make your revisions and submit your changes back to the project maintainer to be merged into the project. You can use someone else's project as a jumping off point and then develop it further for your own use. Forking lets you start your work from the technology that's already available in an existing repository. For example, you might create an alternative version of an open source game or you can enhance or even trim down a public library, so it better serves your needs.

When a project has been abandoned, forking allows you to continue development. You fork that project and pick up from where the original maintainer left off. And this allows a project to continue and thrive. Each GitHub repository offers a fork button. You click that button and copy material from the original repository to a copy that's on your account. The forking process is brief and establishes the new repository under your credentials, and there's always a link back to the original repo from the forked one. Once created, the new repository is otherwise identical to the original. However, it's just a copy. If changes are made to the original after you fork, your repository does not update in sync. So, keep this in mind. After forking, you can clone the forked repository to your computer and work on it. This is the forked version of the repository not the original Bloom Institute of Technology (formerly known as Lambda School) one. Say git remote-v to ensure that your repository's origin points to the forked version. You will not have permission to push changes to a repository that you do not own.

A distributed project allows many people to participate in development at the same time. You submit changes to a coordinated development project through pull requests. Each pull request specifies the changes a contributor wants to make, along with a short document on why those changes have been made. Here's a short program from the repository that I just forked on GitHub. The top left screenshot shows the code before I edited it. The bottom right shows my enhanced code This code introduced is a usage message. And before you worry, you won't need to know C language programming. I picked this example because it was simple, and I wanted to use a language that's not being taught in the BloomTech tracks. I finish my changes at my computer and test them to make sure they work as expected, which they do.

Then I clean up my work, track my file, and create a commit, and I push it to GitHub. My branch is now one commit ahead of the original repository owned by BloomTech. I submit the changes I made in this repository back to BloomTech, by creating what's called the pull request. You click new pull request to start the process. GitHub starts by presenting me with an overview of my changes. These changes appear as a list of differences with my changes to the right and the original source on the left. Once I review my changes and I'm satisfied with them, I click create pull request to move on to the next step in the process. A pull request consists of both a title and a body. The title is automatically generated from your commit message, but you can edit it. Keep your titles short and punchy, preferably under 50 characters. It should summarize what you have changed. The body explains what you have done and why you have done it. Make sure you explain the background of your change and the context it was made in. Never assume anyone who is reading your pull request has full knowledge or background about your work, or understands why you have performed it. Your summary should be clear to anyone who has not carefully memorized a repository's full history and going ons.

When writing up your pull request, use a professional tone and make sure to check your spelling and grammar. This is a professional document you are creating. When you request feedback be clear about your expectations. Say what kind of feedback you're looking for. It could be a quick look or an in depth review. Provide a timeline of when you want this done by. Use GitHub usernames prefixed with the '@' sign to get the attention of people you want notified about your pull request. Any username mentioned in the text will be automatically notified by GitHub. Click Create pull request to submit your changes to the project maintainer. Once submitted, GitHub automatically detects whether there are conflicts that must be resolved by the maintainer. A green checkmark means your changes can be automatically merged, which is a very good thing. Every pull request has a common thread, use the comments to discuss your proposed changes with other people in the community and with the project maintainer.

In real projects, it's not uncommon to have a review period with discussions back and forth in the common thread before an item is merged. If you're working on a real code base, you'll probably want to ask specific people to review your code. The review section on the pull request lets you add specific GitHub usernames to your review panel. You won't normally see this merge pull request button. It's here because I have merged privileges with the BloomTech account. However, even on projects where you are an administrator, you generally want to go through the standard in house procedures and review process rather than skipping the line to merge your own changes. Once merged, the changes from a pull request become part of the official record for your repository. GitHub tracks the commit author, a summary of the commit changes, and the maintainer who approved the change. You try it.