You created our GitHub account and installed Git. Great! Now we’re going to dig in to the real stuff! Let’s use your new tools to contribute to an open source project on GitHub.
Work on an open source project
Click on this link to go to our open source project that needs your help.
Now that we are on the page, let's see what the issues are. Do you remember how to look at the issues?
Click on the Issues tab on top?
It looks like the project owner wants a README file created that contains a description of the project. It also says it's a good issue for new contributors to try. Sounds like a job for us!
Step 1: Fork
Since the open source project does not belong to us, we have to fork it into our own GitHub account. A fork is sending a copy of the original repository to your account (you can think of it as a fork in a tree or a fork in the road: two versions with alternate possibilities). This way, when you submit changes, it will not directly affect the main repository, unless the owner decides to accept them.
Make sure that you are logged in to your GitHub account and then click on the Fork icon on the top right of the open source project page.
You should now have a forked copy available on your own GitHub account. This is where the fun begins.
Step 2: Clone
The next step is to clone that repository onto your computer. Go to the Clone or download button, click in the drop-down, and copy the URL.
Now let's go back to Git Bash. Create a folder for this Git repository, and then route to the file directory on Git Bash.
Now type the command to clone the repository from the forked fixme repo to your GitHub account. Notice that I pasted the cloned URL after the command Git clone:
git clone https://github.com/OCclassprojects/fixme.git
Perfect! Once this is complete, you will have downloaded the project to your local repository.
Step 3: Create your branch
Now that you have your project downloaded, feel free to open the folder and take a look at what’s inside.
There's a folder called
.git, and the
mysong.c file that was in the fixme repo. You will learn more about the file directory in your local repository, so hold tight! First, go to the fixme directory, because that is where we will be working now! You can do that by using the command:
Time to get back to work and fix that issue to make sure our project gets a new README.md file. Remember, you don’t own this project, so you can't just push changes onto the main version in the remote repository. You have a copy of this main codebase on your computer, but typically it's bad practice to just work directly on the main version of a project.
What do we do, then?
Well, you use the master branch, which is another term for the main version of some project code. If you think of your project as a tree trunk, different versions can build off the main code like branches.
You can create your own branch, where you work and make changes without affecting the main version of the code. This version can later be reconnected to the main tree trunk or the master branch.
So, let’s create your new branch. Call it something unique. I will call mine wwbranch. To create my new branch, I will type the following command (you will replace wwbranch with the name you are giving your branch):
git branch wwbranch
Step 4: Check your work with git status
git status in the command line, and note which branch you are working on. Git status is a great way to ensure that you are on the right track, and following all of the steps correctly. Right now, we're on the master branch, so it'll say master branch. To move to your new branch, type in another command to start working directly on that branch.
git checkout wwbranch
Now you should be working directly on the wwbranch (or your equivalent) as your new working directory.
Let's breakdown the above image. Notice that at the end of the first line, it says master in blue. That means that your current working directory is the master branch. In the next line, after you created the branch, it still shows master as your working directory. But in the third line, after you did the
git checkout command, you will see that the branch has switched to the wwbranch.
Step 5: Create and update new file
You can create a new file by typing in the command
touch. To create a new file called README.md, type in the following command:
ls (that is lowercase L and lowercase S for list) and you should see the new file README.md:
You just created a README file and are ready to push your changes for the owner's approval.
Step 6: Add file
Like you saw in the video at the top of the chapter, there are three phases your new file must go through to be integrated into the repository. Let’s type in git status so you can see what I mean.
You should see a readout like the one below:
See how it shows your file as untracked in red? This is the first phase. It means that your file is not part of the repository. The README.md file may exist as a file in your directory, but it isn’t a part of version control yet. So, what is your next step?
The second phase is staging. This is an important process in Git that introduces the file to the repository as a part of version control. Cool! You see, Git still has not saved it as part of the changes. The command to stage your new file is:
git add README.md
Now type in
git status to see that your file is no longer untracked, but staged. Now, if you are sure this is what you want to send to the open source project owners, take the plunge!
Step 7: Commit
The third phase for your README.md file is commit.
To commit is to save the file into version control, where it will exist as part of the archives...forever! This is why it is important to be sure that you are committing the right files. To commit the README.md file you have created and staged, type in:
You should see something like:
That’s it! Your branch is ready to go.
Step 8: Push to remote repository
To send your branch to the open source project with your fixes, you have to push your repo to your GitHub account. Remember how you already set up your credentials with your GitHub account? Here is where you push your branch to the remote repository. Type in:
git push origin wwbranch
You should see something like this:
Congrats! You're almost there. 😁 You can now send your pull request from your GitHub account. A pull request provides your changes for original the main repository owners to review.
You should now be able to go to your GitHub account where the forked repository is, and see a Pull Request button appear. You might have to refresh your page. 😇
Click on that button, and write a descriptive message for the issue you resolved. In this case, you can send a message that says "added a README.md file." Now submit it, and you're done! Click on Create pull request.
You're done! ✨ Guess what? You've just contributed to an open source project, so give yourself a pat on the back! 👏 Now take these skills to the next level and find other projects you would like to be involved with. When you start involving yourself with the open source community, you will gain experience, and meet awesome people.
Now, before moving on to the next part, take the end of part quiz to make sure you've got all the key commands and terminology. From there, we can move on to how to fix all the mistakes you could possibly make while working on GitHub.
You learned a lot in this chapter:
The steps to adding a file to an open source project are: fork, clone, branch, create the new file, add file, commit, push, and pull request.
The main version of a project is called the master branch. You can add a separate version of the project, called a branch, then integrate it back into the master to incorporate the changes.
There are three phases to integrating your file: untracked, staged, and committed.