Contributing Guide

This guide is aimed at beginners who may be making their first contributions to open source or those who may need a refresh.

To get your code merged into a GitHub repository (repo), you should fork the repo to your own GitHub account, clone a local copy of your fork, commit and push your changes, and, finally, send a pull request to the maintainer(s) of the original repo. If your code is acceptable to the project maintainer(s), it will be merged in.

Note: All text within and including angle brackets <PLACEHOLDER_TEXT> is placeholder text and should be replaced before running.


Forking a Repository

A fork is a copy of a repo. Creating a fork will allow you to make changes to the repo's codebase without affecting the original repo.

To create a fork, visit the page of the repo you want to fork on GitHub and click the fork button.

GitHub fork button

This will create a forked copy of the repo on your GitHub account that you can then clone a local copy of. As a fork, your repo will always have a link to the original.

Your fork

Cloning Your Fork

After clicking the fork button, navigate to your fork on your GitHub account and click the Clone/Download button. Copy the URL to your clipboard.

Clone button

This URL will follow a pattern similar to the following:
https://github.com/<YOUR_USERNAME>/<REPOSITORY_NAME>.git.

On your local machine, open a terminal and navigate to the folder where you want to create your local copy of the repo (typically inside a folder called GitHub). Once in the correct directory, type the following code into your terminal and press enter:
git clone <URL_FROM_CLIPBOARD>

This will create a local copy of your forked repo.

NOTE: After cloning your fork, be sure to change directory into the folder created by git in which the repository is located (typically named the same as the repo); otherwise, many of the following commands will not work.


Setting Up Remotes

Remotes are references to remote repos that are stored out on the internet, such as GitHub.com, or the local network.

You can view all of your currently configured remotes for the current repo with git remote -v

git remote -v

origin      https://github.com/brycejech/fccokc_web.git (fetch)
origin      https://github.com/brycejech/fccokc_web.git (push)
upstream    https://github.com/FreeCodeCampOKC/fccokc_web.git (fetch)
upstream    https://github.com/FreeCodeCampOKC/fccokc_web.git (push)

Configure an Origin

When you clone a repository, git should automatically set up a remote called origin that points to the URL you cloned from. However, if no origin remote is set up, you can add it with the git remote add command:

git remote add origin <ORIGIN_URL>

In the above example, <ORIGIN_URL> should be the URL of your forked repo on your GitHub account.

Having an origin set up is important because this is where you will issue pull requests from. Because pull requests cannot be issued from the command line (without additional software), you will need to push your local commits to your origin repository on GitHub and issue pull requests from there.

Configure an Upstream

Upstream is the remote name conventionally used to refer to the original repository from which your fork was created.

Configuring an upstream is useful for keeping your local repository up to date with the original. It is especially useful if you intend to make contributions over an extended period of time to a repository of which you are not an owner or maintainer by simplifying the process of merging changes from the upstream repo into your forked repo.

Note that upstream should refer to the original repo, not your forked version of it. Also, there is nothing special about the name upstream, this can be any name you wish. However, the convention is to use the name upstream for remote references to the original repository from which your fork was created.

Navigate to the original repository's page on GitHub, click the Clone/Download button, and copy the URL to your clipboard.

Use the git remote add command to add a remote reference called upstream:

git remote add upstream <URL_FROM_CLIPBOARD>


Fetch & Merge Changes from Upstream

Once you have added an upstream, you can fetch the latest changes on it with the following:

git fetch upstream

This will fetch all changes on all branches from the upstream repo. Note that this does not actually merge these changes into your local repo.

You can also fetch changes only on a specific branch like so:

git fetch upstream <BRANCH_NAME>

In order to merge these changes in to your local repository, make sure you have checked out the local branch that you would like to merge the upstream changes into, then use the git merge command. Note that you must specify which branch on the upstream you wish to merge into your currently checked out local branch.

git merge upstream/master

Alternative Merging Techniques

Alternatively, you can bring in changes from the upstream repo in a single command with the following:

git pull upstream <BRANCH_NAME>

The above is roughly equivalent to the following:

git fetch upstream
git merge upstream/<CURRENT_BRANCH>

Note that by using git pull, git will not give you any opportunity to review changes before they are merged in. Unless you are sure that you want to bring in all changes from the upstream repo, the fetch/merge technique should be preferred.


Creating a Branch

Now that you have cloned a local copy of your forked repo, you should create a new branch where you will make your changes.

Creating a branch to implement a feature or fix a bug is strongly encouraged because it allows you to experiment without making permanant changes to production codebases.

To create a new branch, use the git branch command:

git branch <BRANCH_NAME>

After creating the new branch, you can switch to it with git checkout:

git checkout <BRANCH_NAME>

You can also do both in a single command like so:

git checkout -b <BRANCH_NAME>


Making and Committing Changes

After creating and checking out a new branch, you can open up your code editor and begin making changes. Any changes made to files in this folder (including file changes, deletions, and additions) will be tracked by git.

Once you have made changes to a file or files, you have to commit those changes to the repo. Before you can make a commit, you must add the changed file(s) to staging.

Use the git add command to add changed files/directories to staging:

git add <FILENAME_OR_DIRECTORY>

Be sure that any changed files or directories that you add to staging are relevant to a single thing. For example, you don't want to fix several bugs, or add several new features, in a single commit because it will be more difficult to roll back, or undo, that commit later. Making small, frequent commits also allows you to make your commit messages concise and specific, which makes it easier for others to understand what the intended result of any single commit is.

You can also add all files in the entire working tree (from the root all the way down) to staging with the -A flag:

git add -A

Once you have added your changes to staging, it's time to commit those changes to the repo:

git commit -m "<YOUR_COMMIT_MESSAGE>"

You can also bypass the staging process entirely:

git commit -a -m "<YOUR_COMMIT_MESSAGE>"

The above will automatically add changed files to staging before committing; however, it will NOT add newly created or deleted files to the commit.


Pushing Changes to Remote Repos

Before you can issue a pull request to the upstream repository's maintainers, you have to push your local commits to your forked repo on GitHub.

Use the git push command to push commits made on your local branch to your fork.

git push origin <BRANCH_NAME>

Most commonly, the name of the remote that you will be pushing to will be called origin. If a branch name is not specified, git will attempt to push the current branch onto the remote branch of the same name but will error out if the remote branch does not exist. If a branch name is specified, git will update the remote branch or create it if it does not exist.


Creating a Pull Request

You are now ready to issue a pull request from your newly published branch.

To issue a pull request, go to your forked repository's page on github.com and click the "New Pull Request" button

Pull Request button

You may first want to switch branches to the branch you want the pull request applied from. By first switching branches, when creating a new pull request the correct head branch will already be selected for you.

Pull Request

When creating a pull request, the base branch is where the changes should be applied to and the head branch is where the changes should be applied from (IE your branch).

After you have selected the appropriate base and head repos and branches, you need to create your commit messages.

Pull Request Comments

The first message is the title, it should briefly describe what the pull request should accomplish.

The second message is where you should be more descriptive about the changes contained in the pull request. You can list files that have been updated, give more detail about what the changes should do, reference or close any issues related to the pull request, etc.

Many project maintainers will include a template that describes the type of information they expect a pull request to contain before they will merge it in. If the repository conains a file called PULL_REQUEST_TEMPLATE, this will be used when creating new pull requests.

After creating your commit messages, click the "Create Pull Request" button to finish creating the pull request.

Create Pull Request button

Cleaning Up

If your pull request has been merged in or rejected by the upstream project's maintainers and you do not wish to keep it, you can delete branches with the git branch command.

git branch -d <BRANCH_NAME>

The above snippet will delete a branch as long as it has been merged in to another branch or error out otherwise. To force delete a branch use the -D flag instead.

Remote branches can also be deleted with the git push command using the -d flag.

git push -d <REMOTE_NAME> <BRANCH_NAME>