Recently I've been heavily impressed by the open-source community and I've inspected a lot of packages since. It's great to see the community help eachother out and Pendo is definitely planning to become more active in the open-source field. But, I have got to be honest: there's a lot to learn if you want to contribute the right way. Don't get me wrong, contributing is greatly appreciated, but to ensure code quality there are a bunch of things to learn and I've just started..
Hopefully, Pendo will inspire others to contribute to the community as well and creating this blog is to share my first experience because it took a while to get my heads wrapped around every single aspect so far.. big shout-out to Spatie.be, this webagency based in Antwerp is heavily involved in open-source and by reading their packages and articles a lot of vague things got clear instantly.
Pendo's first package: Laravel FontAwesome
The package I created is a small package that was inspired by a similar one (lucasruroken/laravel-font-awesome). It seemed like an easy entrypoint to creating packages and package development for Laravel: a ServiceProvider, a Facade and a class. We've been working with similar files for quiet some time now, but never had the guts to create our own at Pendo ;-). The package I created contains a single method to generate an icon from within your code, besides that it also has a Blade directive to generate icons from without your templates easily! You can view the package at Github. Below I've outlined most steps I had to take to release a stable, tested version of this package and more important: all issues I've encountered along the way.
The first thing had to conquer was creating a composer file for the package and setting the file structure. By following this tutorial I got to know the basics. After running the command `composer init` from the terminal from within the package folder, you're presented a list of questions you have to answer and the composer.json file is included automatically. A few steps later I noticed the importance of this file: when struggling to get the tests to work it turned out I had to include phpunit in the require-dev section of composer.json. Also setting the minimum PHP version to PHPUnit's requirements was needed when the TravisCI builds failed at first. By the way, when testing the package stand-alone don't forget to install the composer depencies!
Packagist & Git tagging
Adding the files to a Git repo is a task we've done numerous times already at Pendo and adding the repository as a package on Packagist.org was easy aswel. The previous mentioned article explains how to do this well enough. But why wouldn't composer install our package in a fresh Laravel installation? It kept complaining about the minimum stability level. After diving into Google (once again) it turned out you have to tag a version at Git (don't forget to auto-sync Git with Packagist) before Packagist sees it as a stable version. So... after tagging the software as version 1.0.0 I could finally run `composer require pendonl/laravel-fontawesome`. (Font)Awesome!
TravisCI, StyleCI, Scrutinizer & Insight
I've got to admit: I had absolutely no idea what all these tools did before I started this morning. When browsing Git repositories the badges of these tools all over the place but it never occured to me to see whats behind the badges. StyleCI is a tool that checks the coding style you've used and after analyzing you're presented wether or not you passed their tests. For me, this was a great way to see what coding conventions I still need to make myself a second nature, Scrutinizer and Insight do about the same in their own way. TravisCI is another automated tool, it get's triggered when you push a new version to your repository: it fetches your code, installs the composer dependencies and runs the tests you've added, if anything failes the build doens't pass and you can act accordingly to fix the errors.
Another new thing was testing.. I noticed most, if not all, major packages provided tests along with the package. Eventually (after using TravisCI) I spotted the huge benefit of having tests, but also this part took a while to get up and running. Writing the tests wasn't that hard since the FontAwesome-package only had to assert equals in two different tests, but how to run these tests was a completely different story. First of all, I didn't have PHPUnit globally available to run tests (composer require global phpunit/phpunit) and second of all there must be a phpunit.xml file before running tests in the console and in any automated tool is going to work! The phpunit.xml unit file was probably the hardest to understand, but with a little bit of help of this article I ended up with a working test suite!
The final issue I got was `composer update` not working.. although I had pushed various code updates to the Git repo which reflected on Packagist, but the command did nothing. Even after tagging the code to a new version my console didn't mention an update and Git just told me the code was already up-to-date. Turns out there's a special Git command to push a tag: `git push --follow-tags`, after running this command the latest version became visible in Packagist and running composer update would finaly add the latest code to our project! P.S. If you have any problems you might want to check the version of your package in composer.json!
Another small issue I want to write down was my project's .gitignore file, one of the tools to rate the code quality mentioned a line in the .gitignore file that was supposed to be in the global .gitignore file. Being aware of the existence of this file made my life easier for upcoming projects: all files in the global gitignore are now ignored by Git by default in every project.
As I already said: it was my first experience with open-source and I'm pretty sure I don't know all ins and outs yet because there's so much to learn! If you have any comments or improvements on this article let us know by sending a tweet or commenting on this post! Needless to say: today was a great experience. I've got to work with a lot of new tools, learned new things, got new insights and above all I enjoyed creating something to give back to the community.
Reageer gerust als er vragen of opmerkingen zijn, we horen niets liever dan de reacties van onze klanten en volgers om ervoor te zorgen dat we scherp blijven!