A beginner’s guide to contributing to the GitHub project

• The Beginner’s Guide to contributing to a GitHub project
• Originally written by Rob Allen
• The Nuggets translation Project
• Permanent link to this article: github.com/xitu/gold-m…
• Translator: Sophia
• Proofread by: MaoqyHz Isabella

This is a beginner’s guide on how to contribute open source on GitHub. This guide is based on how I saw the Zend Framework, Slim Framework and Join.in operate. However, this is only a general guide, so check your project’s README file first for details.

Step 1: Set up the working copy on your computer

First you need a local clone of the project, so hit the “fork” button on GitHub first. Pressing the button will automatically create a copy of the project repository in your GitHub account, and you’ll see a comment below the name of the project that has been forked:

Now you need a local copy, so find the “SSH Clone URL” in the right column and use it to clone on your local terminal:

$ git clone [email protected]:akrabat/zend-validator.git
Copy the code

As shown below:

Go to the new project directory:

$ cd zend-validator
Copy the code

Finally, at this stage, you need to set up a new remote address pointing to the original project so that you can grab any changes to the original project and update them to the local copy. Start by locating the link to the original project — it’s at the top of the GitHub page, via the “fork from” tag. This link will take you back to the original project’s GitHub home page, so you can find the “SSH Clone URL” there and use it to create a new remote, called upstreams.

$ git remote add upstream [email protected]:zendframework/zend-validator.git
Copy the code

You now have two remote ends of the project on disk:

1. Origin: This points to the GitHub project for your fork. You can commit and pull updates to that remote.
2. Upstream: You can only pull code updates from this upstream remote, not modify it.

Step 2: Start contributing

branch

The first rule is to put each change on its own branch. If your project uses Git-flow, it will have both a Master and a Develop branch. As a general rule, if you’re fixing a bug, pull down a new branch from master. If you’re adding a new feature, pull down the new branch from Develop. If the project has only one master branch, pull the new branch directly from that master. Some projects, such as Slim, use branches named after version numbers (2.x and 3.x). In this case, select the relevant branch.

For this example, let’s say we’re fixing a bug in the Zend-Validator, so we pull a new branch from master:

$ git checkout master
$ git pull upstream master && git push origin master
$ git checkout -b hotfix/readme-update
Copy the code

First of all, we want to make sure we’re on the master branch. The Git pull command then synchronizes our local copy with the upstream project, and the Git push command synchronizes it to the GitHub replica project in our branch. Finally we create our new branch. You can name your branch however you like, but it better make sense. For example, it is often helpful to include an issue number in the branch name. If the project uses Git-flow like zend-Validator, the branch name is prefixed with either “hotfix/” or “feature/” in a specific naming convention.

Now you can start your work.

Make sure you only fix what you’re dealing with. Do not try to fix other issues you see during the fix, including formatting issues, as your PR may be rejected.

Make sure you commit in logical blocks. Each commit message should clearly indicate what changes have been made. Read Tim Pope’s Notes on Git commit messages.

Step 3: Create a PR

To create PR, you’ll need to push your branch to the Origin remote and then press some buttons on GitHub.

Push a new branch:

$ git push -u origin hotfix/readme-update
Copy the code

Doing so will create a new branch on your GitHub project. The -u flag connects the local branch to the remote branch so that you can push to the remote branch in the future simply by typing Git push Origin.

Back to the browser and navigate to your fork project (in my example address is: https://github.com/akrabat/zend-validator), you will find your new branch listed at the top of a simple “Compare & pull request” button:

Go ahead and press the button!

If you see a yellow box like this:

Clicking on the link takes you to the CONTRIBUTING file for the project and you need to read it! It contains valuable information on how to use the project’s codebase and will help you get your contributions accepted.

On this page, make sure “Base fork” points to the correct repository and branch. Then make sure you provide a good, concise title for the pull request and explain why you created it in the description box. If you have a relevant issue number, please add it.

If you scroll down a bit, you’ll see how your changes differ from the original version. Double check if it is the result you want.

If you think you have no problems, press the “Create Pull Request” button.

Step 4: Review by maintenance personnel

In order to integrate your changes into the project, the maintenance staff will review your changes and request changes or merges it.

Lorna Mitchell’s article code Review: Covers what the maintainer will be looking for before you run the code, so read it and make sure you don’t bother the maintainer.

conclusion