These days I'm working with a colleague in a PHP package for extending Laravel called laravel-crud.
This package adds some functionality to Laravel in order to speed and have a cleaner code for typical CRUD resources in a Laravel application.

The code is hosted on Github and the package is already published and can be included in any project by adding it to the composer.json file but, what are the exact steps in order to contribute to the package, select an issue, write the new code, test it, and finally include the solved issue in the final published code? This is a small guide on doing it:

Setting up

First things first, the environment must be set up. As this is a framework extension, the package is not intended to be used as a standalone, so a test application must be built and then the package included to its composer.json file, this will allow us to test the package in a real world environment and to check things manually. We will call it laravel-crud-test-project.

After doing that, the require section on the test project's composer json file will look like this:

 "require": {
        "php": ">=5.5.9",
        "laravel/framework": "5.2.*",
        "carlosafonso/laravel-crud": "dev-master"
    },

Also, as we are going to modify the code for the package itself we have also to first fork the repository on Github and then clone this forked repository.

So after doing it we end up with two folders, laravel-crud and laravel-crud-test-project, one for the project that uses the package and the other for the package itself.

Selecting and fixing an issue

Now that the everything is set we are ready to start, and we should do this by selecting an opened issue, in my case I chose this one.

After the proposal on the Github issue and after the approval I create a new branch on my local copy of the package code, I will give a name somehow related to the issue name, in my case it was git branch base-model-interface.

Then you can start editing the code and committing and pushing the changes to this new branch on your forked repository.

During this process, you would probably need to see these changes you are doing on the test project that uses the package, but the test project still uses the composer published version and the changes won't be there. How to tell the test project that it must use the version you are modifying instead?

You have to edit the test project's composer json file and use a VCS repository. A repositories section must be added like this:

	"repositories": [
		{
			"type": "vcs",
			"url": "https://github.com/namelivia/laravel-crud"
		}
	],

It contains a reference to our forked repository url on github.

Now in the require section of the same composer file, replace the line you had for requiring the package:

"carlosafonso/laravel-crud": "dev-master"

For this one:

"carlosafonso/laravel-crud": "dev-base-model-interface"

Note that the package name is still the same, the one for the original package, not our forked repository. However the branch name corresponds to the branch name we are working with in our forked repository, preceded by dev-

Then just execute composer update and then the package will update to the version you are modifying and you cant test it.

Adding your code to the composer version

Once the issue has been fixed your code has to be approved and included on the package. The first thing to do is to rebase the commit, this is needed for one thing, if you have made several commits to your local branch like Fixing the issue, fixing a typo, small fix, big fix for the previous fix you don't want all those commits to appear in the final repository commit history. Once everything is working and your commit is included in the final version, the ideal commit message would be like this Fixing the issue. I will not enter in the details of rebasing as there are several guides on doing this, like this one from Atlassian.
Just take care of keeping the original repository commit history as clean as possible.
Then you can create a pull request on Github, check if the build goes well and wait for it to be approved. Finally delete your local and remote branches. The issue can then be closed and your code will be finally part of the published composer version of the package.

And that's all! I hope you enjoyed this guide and found it useful, also don't forget to check our package on Github, specially if you a Laravel developer. You can try it, leave your impressions and even star it if you like.

See you next time!