github how do you know what to contibute to

This is a guide to contributing to an open source project that uses GitHub. It'due south mostly based on how I've seen Zend Framework, Slim Framework and joind.in operate. Yet, this is a general guide so check your projection's README for specifics.

TL;DR

Skip to the summary.

Step ane: Prepare up a working copy on your reckoner

Firstly you need a local fork of the the project, so go ahead and press the "fork" push button in GitHub. This will create a copy of the repository in your own GitHub account and you lot'll meet a note that it's been forked underneath the project proper name:

Now you lot need a copy locally, so discover the "SSH clone URL" in the right paw column and use that to clone locally using a terminal:

$ git clone git@github.com:akrabat/zend-validator.git

Which volition do something similar this:

Modify into the new project's directory:

$ cd zend-validator

Finally, in this stage, you demand to set a new remote that points to the original project and then that yous can take hold of whatsoever changes and bring them into your local copy. Firstly clock on the link to the original repository – it's labeled "Forked from" at the superlative of the GitHub page. This takes you dorsum to the projects chief GitHub folio, then you tin find the "SSH clone URL" and use it to create the new remote, which nosotros'll call upstream.

$ git remote add together upstream git@github.com:zendframework/zend-validator.git

You at present have two remotes for this project on disk:

1. origin which points to your GitHub fork of the projection. Y'all can read and write to this remote.
2. upstream which points to the chief project's GitHub repository. You tin can only read from this remote.

Step ii: Go information technology working on your machine

Now that you have the source code, get it working on your calculator. Hopefully there will exist documentation how to exercise this in the README or INSTALL file.

If you lot go it working, but the documentation is unclear, and so improving that bit should exist your first PR to the project. This happens to me a lot and I've updated getting-started docs a lot equally my first PR to a project!

Step iii: Practise some work

This is the fun flake where yous get to contribute to the project. It's usually best to start by fixing a bug that is either annoying you or you've found on the project'south effect tracker. If you're looking for a place to start, a lot of projects use the "easy pick" label (or some variation) to indicate that this issue can be addressed past someone new to the project.

At present that y'all have picks an result, reproduce information technology on your version. One time you accept reproduced it, read the lawmaking to work out where the problem is. Once y'all've found the code problem, you lot can move on to fixing information technology.

Co-operative!

The number one rule is to put each piece of work on its own branch. If the project is using git-flow, then it will have both a principal and a develop branch. The general rule is that if you lot are bug fixing, then branch from master and if you are calculation a new characteristic and then branch from develop. If the project only has a chief branch, the co-operative from that. Some projects, like Slim use branches named after the version number (2.x and 3.x in Slim's case). In this case, pick the branch that'due south relevant.

For this example, we'll assume nosotros're fixing a bug in zend-validator, so nosotros branch from chief:

$ git checkout principal $ git pull upstream master && git button origin master $ git checkout -b hotfix/readme-update        

Firstly we ensure we're on the master branch. So the git pull command volition sync our local re-create with the upstream projection and the git push syncs it to our forked GitHub projection. Finally we create our new branch. You tin can name your branch whatever yous like, only it helps for it to be meaningful. Including the event number is usually helpful. If the project uses git-flow as zend-validator does, and then at that place are specific naming conventions where the co-operative is prefixed with "hotfix/" or "feature/".

At present you can do the piece of work to fix the issue.

If the project has tests, run them to ensure you lot haven't broken annihilation. You may besides add a new test to testify that your change fixes the original trouble.

Ensure that you only set the thing you lot're working on. Do non be tempted to fix some other things that yous see along the manner, including formatting bug, every bit your PR will probably be rejected.

Make certain that yous commit in logical blocks. Each commit message should be sane. Read Tim Pope'south A Notation Nearly Git Commit Messages.

Step 4: Create the PR

To create a PR you need to push your branch to the origin remote and then press some buttons on GitHub.

To push a new branch:

$ git push -u origin hotfix/readme-update

This will create the branch on your GitHub project. The -u flag links this branch with the remote one, and then that in the future, yous can merely type git push origin.

Swap back to the browser and navigate to your fork of the projection (https://github.com/akrabat/zend-validator in my case) and you'll see that your new branch is listed at the tiptop with a handy "Compare & pull asking" push:

Become ahead and printing the push button!

If you see a yellow box like this:

Click the link which will accept you to the project's CONTRIBUTING file and read information technology! Information technology contains valuable information on how to piece of work with the project'southward code base and volition help you become your contribution accepted.

On this folio, ensure that the "base fork" points to the correct repository and branch. Then ensure that yous provide a practiced, succinct championship for your pull request and explain why you have created it in the description box. Add any relevant issue numbers if you have them.

If yous scroll down a chip, you lot'll see a diff of your changes. Double cheque that it contains what you lot look.

Once you are happy, press the "Create pull request" button and you're done.

Step five: Review by the maintainers

For your piece of work to be integrated into the project, the maintainers will review your work and either asking changes or merge it.

Lorna Mitchell'south article Code Reviews: Before Y'all Fifty-fifty Run The Lawmaking covers the things that the maintainers will wait for, so read it and ensure you've made their lives as easy as possible.

To sum upwards

That'due south all there is to information technology. The fundamentals are:

1. Fork the project & clone locally.
2. Create an upstream remote and sync your local copy before you branch.
3. Branch for each separate piece of piece of work.
4. Do the piece of work, write good commit messages, and read the CONTRIBUTING file if there is i.
5. Push button to your origin repository.
6. Create a new PR in GitHub.
7. Respond to any code review feedback.

If you want to contribute to an open source project, the best i to pick is one that you are using yourself. The maintainers will appreciate it!

kittermanthercured1984.blogspot.com

Source: https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/

Share this post