When you're contributing to a project, you typically don't edit the project directly. You create a copy of the project's repository, or repo, for yourself and make all of your changes there before submitting them to the project. This copy is called a fork.

To begin, you must be signed into your GitHub account. Then use a browser to navigate to the repo for the project to which you plan to contribute. I'm going to be contributing to the Adafruit Learning System repository.

The first thing you want to do is fork the repo. Click the Fork button on the right side of the page to fork a copy of the repo to your account.

Great job! You now have your very own GitHub copy of the project repo to which you're going to contribute. You're ready for the next step!

Clone Your Repo

The next thing you'll need to do is download a copy of your new repo on your computer so you can start working on it. This is called creating a clone or cloning. Create a directory on your computer to hold your projects. Mine is in my home folder and is called repos.

On the page for your repo, you'll find a green Code button.

Click it to find the clone URL for your new fork. The URL will look something like this:

https://github.com/TheKitty/Adafruit_Learning_System_Guides.git

(TheKitty is my GitHub username, yours will be different)

Click the Copy button to copy the URL to your clipboard.

Now to fire up git on your local computer. This may vary by operating system, on Windows there is a Git Bash icon.

If you wish to create a new directory to place the files in locally, you might wish to do that prior to starting git.

Open your terminal program and navigate to your new directory using the cd command. I put my repos in a directory on my Windows S: drive named git:

When you clone a repo, Git assigns the repo on GitHub an alias, which by default is "origin". You may in the future have a reason to clone a repo that is not your own fork, and it can be confusing when all repos are called origin.

So, for repos, Adafruit suggests setting the alias to the repo owner's GitHub user ID. In the case of this fork, this is my GitHub user ID. This makes it easier to remember when I'm contributing to my own repos versus contributing to someone else's repo.

Once you're in your new directory, enter the clone command. Replace youruserid with your GitHub user ID, and paste the URL from your clipboard (obtained above in GitHub):

git clone -o youruserid https://your-fork-URL

This will create a local copy of the repository on your computer in a directory with the same name as the repo. So, now I have a new directory, /s/git/Adafruit_Learning_System_Guides, which contains a copy of the newly forked repo.

Now, use the cd command to move into that directory.

Remotes

When changes are merged with the project, they're merged into the original repo. This includes your final changes and changes submitted by others.

Changes made to the original repo do not automatically update to your repo. You have to manually fetch those changes and merge them into your own repo. To do this, you need to add what is called a remote. A remote allows you to fetch the changes from the original project to stay updated.

Back in GitHub, use your browser to navigate to the page for the original repo. Click the Code button, then click the copy button to copy the URL for the original repo to your clipboard. Remember to use SSH if you setup GitHub to use it.

When you create a copy of a project, the original project is considered to be upstream. Since you're getting the updates from upstream, often the remote is called upstream.

However, in exactly the same way we called your remote your GitHub ID, it's easier to call the original remote by the owner's GitHub ID. The original repo here is owned by Adafruit, so it is suggested to name the remote adafruit.

While in the directory for your newly cloned repo, enter the following remote command, changing ownerID to the original project owner's GitHub ID (for the Adafruit Learning System, it is adafruit), and entering the URL from GitHub obtained above:

git remote add adafruit https://original-project-url

Your local repo is set up and ready to go. You forked the repo, cloned a local copy, and prepared to keep it updated.

Now you're ready to begin working with it!