As craftspeople, it’s important to keep our skills up-to-date, but to also look after the tools we use to avoid them becoming rusty and obsolete.
By contributing back to your favourite tool to make it better, you not only improve your own experience, you improve the stability of the product for others and ensure it's fit for whatever version of system it will run on.
If you have a passion to learn and a desire to leave a project in a better state than you found it, you are in a prime position to begin contributing to open source.
But contributing features to open source projects can be daunting, especially if you are new to open source. Where to start? How to ensure what you add is helpful?
In this short guide, I will take you through the process of building a new feature, testing it and then most importantly, getting open honest feedback.
Step 1: planning
So you have found something you can fix or improve. Fantastic. The next step is to plan, plan and plan again, especially if working on a big feature. Use your weapon of choice: a whiteboard, post-its on the wall, or even sheets of A4 with blu-tac (some of my favourite design tools).
In my first contribution, I did not plan thoroughly enough. I began working on my fork, unaware that it was seriously out-of-date and I was also working on the wrong part of the project.
If you have forked the project, I would highly suggest the following tutorial from Github on keeping your forks up to date:
Step 2: build
Clone your fork and then install all of its dependencies. Then stop and run the tests. There can be nothing worse than starting on a broken branch or finding out halfway into your feature that the bug you are trying to decipher is a known issue and would have saved you some time.
Once all the tests have passed, go ahead and create your feature branch. Regardless of the version control tool you are using, don’t work on your master.
I am pretty easy going for which tools you need to start developing (Vim *cough*). However, when working on a feature for PhpSpec, I did find having PHPStorm and the Symfony plugins really helpful to help trace and jump to the next class or interface. Not fighting your environment is great and helps to improve the enjoyment of contributing back. Unless you are trying to improve your knowledge of <insert reader tool of choice here>.
Something to be aware of is that your project could have a minimum set of requirements and one of them is to support various legacy versions. Under the next section on testing I’ll explain more on how you can do this using Docker.
Next comes the build. Always start small and raise a PR for some early feedback or at least to allow the branch to verify against any continuous integration tools like Travis CI or Scruitnizer.
At this stage, it may take a while for the contributors to provide feedback, depending on how active the community is. It is really important not to take anything as a criticism against you. You are looking for the opportunity to improve your skills and leave the project in a better state for the next developer. Take on feedback and do feel free to ask for clarification if you are unsure of anything.
Take the advice, refactor or make the suggested changes if required and then submit a final PR. During this time you should be adding or improving the tests to accommodate your new feature.
Step 3: testing
Docker provides a great solution to allow you to test quickly against multiple versions and I would reccomend this project (https://github.com/inviqa/dock-cli) for managing docker containers.
When I was contributing to PhpSpec, I used the following commands to test against PHP and HHVM. The beauty of Docker is it will fetch the containers if they are not installed and using the Docker commands below, it will clean up the containers at the end of the run.
docker run --rm -it -v $(pwd):/phpspec -w /phpspec php:7 bin/phpspec r --format=progress && vendor/bin/behat --format=progress [email protected]
docker run --rm -it -v $(pwd):/phpspec -w /phpspec jolicode/hhvm hhvm -ddate.timezone=Europe/London bin/phpspec r && vendor/bin/behat --format=progress [email protected]
bin/phpspec r && vendor/bin/behat --format=progress [email protected],[email protected]
I assumed that my local PHP version (5.5) was enough to test locally and that Travis CI would capture any boundary issues with PHP 5.3 – mainly the differences in array initialisation [ array() vs  ] and assignment were the issues in this case.
If your project didn’t come with any testing tool, then why not try and introduce some using a BDD tool such as Behat to capture the requirements and provide a great way to document the expected behaviour.
Step 4: submitting your feature
The feedback you gain can be insightful, and might cover anything from poorly configured IDEs, to not following the coding standards, or over engineered solutions. The community will be there to keep you honest.
Don’t be afraid to push back if you need to, however, and also don’t be afraid to refactor to a more acceptable solution that will leave the codebase in a better state for everyone. This cycle can take anywhere from one day to a couple of months to get right before your PR will be accepted.
Then wait for the beta to be released for testing. After a period of time, if there are no issues then that release gets merged and a tag is created. It’s on that day you get to celebrate.
It may sound like a lot of work. However, it’s also addictive and you might quickly find more and more things you want to tidy up.
Welcome on board. You’ve officially got the bug for open source contributions!
Feedback and learnings
Although this work may seem simple in some parts, my experience was over the course of many hours in the evenings and weekends. I came up against many problems, including not syncing my branch and rebases that would not work correctly.
During this six-month period, the project I was contributing to was also releasing additional versions which had to be rebased into my branch. It was actually during this holding period where I developed an extension and tried to find new ways to contribute back further to the community and learn what running a project was about.
I hope I have given you a taste of what contributing to an open source project is like, especially one that is used by loads of developers. If you feel ready to contribute then have a look at the issue list and pick one up by leaving a note.
If you still feel unsure, then help review a PR, you will be amazed what effect you can have helping someone else clean their PR up for submission and this is a prime opportunity to practice your PSR compliance skills.
To that end, I have to thank Ciaran McNulty, the lead maintainer of PhpSpec, for his guidance when it came to the PhpSpec core and to the other contributors and maintainers who gave their invaluable feedback when I submitted my PRs for review.
I’ll end this post with something I heard recently and also another great reason why you should help on open source projects:
Many eyes make all bugs shallow – Linus’s law
Helpful links and documents
Twitter handle: @Elfiggo
Extension Building for PHPSpec: https://inviqa.com/blog/how-build-extension-phpspec.