Contributing to a project or package

opensource-contributions.md

Contributing to a project or package

Tools used

• OpenSource Project - simplesamlphp project
• Platform - Github but any code versioning software could work

Fork the project & clone it locally.

Click the "fork" button in GitHub. This will create a copy of the repository in your own GitHub account and you’ll see a note that it’s been forked underneath the project name.

Create the local copy

git clone https://github.com/simplesamlphp/simplesamlphp.git

Create an upstream remote and sync your local copy before you branch.

You might find that you already this setup: type the command below to review. In my case, they were already there as seen below.

git remote -v
origin  https://github.com/KalemaEdgar/simplesamlphp.git (fetch)
origin  https://github.com/KalemaEdgar/simplesamlphp.git (push)
upstream        https://github.com/simplesamlphp/simplesamlphp.git (fetch)
upstream        https://github.com/simplesamlphp/simplesamlphp.git (push)

If its not there, then create it as below.

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

• origin which points to your GitHub fork of the project. You can read and write to this remote.
• upstream which points to the main project’s GitHub repository. You can only read from this remote.

Branch for each separate piece of work.

The number one rule is to put each piece of work on its own branch. The general rule is that if you are bug fixing, then branch from master and if you are adding a new feature then branch from develop. If the project only has a master branch, the branch 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’s relevant.

My setup from simplesamlphp

git checkout master
git pull upstream master && git push origin master
git checkout -b fix/modules-url-fix

• Firstly we ensure we are on the master branch.
• Then the git pull command will sync our local copy with the upstream project and the git push syncs it to our forked GitHub project.
• Finally we create our new branch. You can name your branch whatever you like, but it helps for it to be meaningful.
  • Including the issue number is usually helpful.
  • If the project uses git-flow as zend-validator does, then there are specific naming conventions where the branch is prefixed with "hotfix/" or "feature/".

Do the work, write good commit messages, and read the CONTRIBUTING file if there is one.

• If the project has tests, run them to ensure you haven’t broken anything.
• You may also add a new test to show that your change fixes the original problem.
• Add the changes to the branch and commit the changes.

Push to your origin repository.

$ git push -u origin fix/modules-url-fix

Create a new pull request (PR) in GitHub.

• Once the changes are committed to your local repository, you can submit a PR by clicking Compare and Pull request button within GitHub to submit the PR.
• Ensure that the base fork points to the correct repository and branch.
• Then ensure that you provide a good title for your pull request and explain why you have created it in the description box.
• Add any relevant issue numbers if you have them.

Respond to any code review feedback.