Treehouse
writes on January 26, 2017
This article is specifically for people who are evaluating packages for their project. I will occasionally mention PHP specific technologies, but most of what is cover here should apply to any language you use. If you’d like to learn more about package management for PHP, check out our course on Dependency Management with Composer. If you’d like to learn more about package management for JavaScript, check out our course on npm Basics. This course also includes a great video on comparing packages. If you are looking for some great tips for writing your own package, my friend @reinink has a great checklist at phppackagechecklist.com.
The Good, The Bad, and The Ugly
When using a package, it all really boils down to one thing: you don’t maintain the code.
This can be good. You can benefit from more experience with specific areas than you or even your team may bring to the table. These packages may be more robust and handle security vulnerabilities better than you could. They can also help you launch a product more quickly by allowing you to wire together the pieces that are already done. Don’t reinvent the wheel.
But, because “you don’t maintain the code”, this can also be bad. The packages may have MANY more features than you will ever need, making those packages harder to maintain or secure. You also don’t have any control on how the maintainers may change the code. And if you need a new feature or something changed, you could be back to square one. The maintainers may not choose to implement your suggestions, and if you change it yourself, you may be violating the terms of the license or, at the very least, it’s not your code but you have to maintain a branch of the original code.
Finally, because “you don’t maintain the code”, it can be ugly. And I’m not just talking the code itself, although there is definitely very ugly code. You often make architectural decisions based on the tools at hand. If one of those tools is a package that does things in a specific way, you may mold your own program into matching with these package designs. Multiple packages may not always fit together nicely. And upgrading ANYTHING can be a nightmare! Your code, the packages, your server. The number one security vulnerability is unpatched software.
So how can we make the best use of the good, while minimizing the bad and the ugly?
Choosing Packages Wisely
This list doesn’t guarantee that a package is the correct choice for your project, but following these suggestions can help you narrow down your choices and make a more informed decision.
1. License
If a package doesn’t have a license, it doesn’t mean you can do whatever you want, it actually means that legally you can’t use that code. Make sure the package has a license and that the license permits your application to use the code in the way you want. This can vary greatly depending on your application’s use case. Is it a website? Or software you’re selling? Or software you’re giving away? Or even repackaged code? Take a little time upfront to Learn about Open Source Licenses so you don’t get into trouble later on.
2. “The Bus Factor”
This is the polite way of asking what would happen if one of the package maintainers got hit by a bus? A bus factor of one means there’s only one core contributor and the package would most likely be abandoned if that person got hit by a bus. Look for packages that have many contributors and/or are used by large projects that may take over the maintenance of the package in the event that the current maintainers are unable to continue their work.
3. Written by a Respected Group
Not only does choosing a package written by a group help with “the bus factor”, there are a number of other benefits as well. Often they will hold each other to high standards like The League of Extraordinary Packages. They have other peers with whom they can share ideas and get help along the way. They also have the experience that comes from releasing and supporting more packages.
In the PHP community, there are a number of well-respected groups that put out numerous packages.
4. Test Coverage
Just like with your own code, when features are covered with tests, you can have more confidence that they are working the way they were designed. You can also feel more confident that any updates will not break the features you are using. This can also be an indication of how serious the maintainer is about their package.
5. Package Management
Is the package you wish to use available with the package manager you are using? If not, the chances of keeping up to date with the package, and even remembering what packages you are using, are significantly reduced.
For PHP, this will typically mean that it is distributed via Composer on Packagist.org. For JavaScript, this typically means npm.
6. Uses Semantic Versioning
Semantic Versioning is a design scheme that helps you maintain package updates for security and bug fixes. It also makes it easier to utilize new features that aren’t going to break the code you are already using.
Under this scheme, version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next. Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible Application Programming Interface changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Learn more about Semantic Versioning.
7. Documentation
Good documentation can make or break the effectiveness of a package. This refers to the instructions for using the package primarily, but also well documented code. If using a package is going to cause more problems than it solves or take more time to implement then it would take you to write and maintain your own solution, you probably don’t want to use that package.
8. Good Change Log
Can you find good records of what has been changed, when it was changed, and by whom? This can be helpful in determining if any issues are being resolved or if the package is stagnant. It’s also good to look for upcoming changes and new features that may be added in the near future. Do they listen to users implementing their package and do they make changes accordingly? This can help determine how your own request may be treated in the future
9. Follows a Coding Standard
Following coding standards applies to a number of areas. First of all, following a style guide will help the code to be more easily read. Second, following standards for middleware will help you more easily switch out one package for another when your requirements change. For example: if you’re using a logging package that follows the logging standards (by implementing the logging interface), when you switch from one logging system to another, the changes to your code should be minimal.
You can find some suggested PHP Coding standards here https://github.com/php-fig/fig-standards/tree/master/accepted
10. Engagement
How many other people are using this package? The more people that are using the package, the more likely that the package actually works, issues get found faster, and there are more voices to make sure that those issues are taken seriously. If the package is on GitHub you can look at watchers, stars, forks, issues, pull request and pulse. These are good indicators of how active and engaged the package is. Sometimes no recent updates means the package is “done”, but if you’re considering a fairly large package that hasn’t been updated in 2 years, it’s probably time to look for something else.
11. Welcomes Contributions
And finally, if you do run into an issue or new feature you would like to see in the package you choose, how open are they to suggestions and contributions from the community. Getting involved can help you improve your own code, gain experience and also improve the packages you use along the way.
Conclusion
No one can see the future, so you can never be sure that a package won’t be abandoned or your need for a particular package might change in the future. By making an informed decision the benefits of having large chunks of code that you don’t have to maintain far outweigh the possible downsides. Whatever decision you make, pay attention to security vulnerabilities and keep your code, packages, and server as updated as possible.
