Better Practice, Dec. 2018

http://www.phparch.com \ December 2018 \ 39

Producing Packages, Part Three

The Workshop

Handling a PR You Don’t Want The pull request you don’t want is always harder than ones you want. You want to be respectful of the author for taking the time to make changes to your code. We want to always ensure we understand where the author is coming from so we can understand why they think the change is needed. You don’t have to become their best friend but make sure you spend enough time to wrap your head around what they want to be able to do. If what they want just doesn’t fit into your defined scope merely let the user know. Remember to be tactful and respectful with your comments. Closing the pull request without merging is like a door slamming shut; try to close the door as gently as you can. No one enjoys rejection, but unfor- tunately closing pull requests once they’ve been determined they are no longer needed is part of the job as an open source maintainer. There can be multiple reasons: the change wasn’t wanted/needed, another author beat them to the punch and solved the issue in a better way, or something else. Regardless, remember to have empathy and respect when commenting on why you’re closing the pull request without merging.

Last Steps for Pull Requests Once we’re happy with the changes, we can hit the big merge button! Make sure to thank the contributor for their time! Now we have changes in our master branch. They haven’t been tagged in a release, so we need to tag a new release.

Tagging New Releases

Tagging a new release communi-
cates to users what has changed from
one release to the next. In this context,
releases can also be called versions
which is another common way to refer-
ence a release. The de facto standard for
how we number our releases is to use
Semantic Versioning^5 where we have
a version separated with two decimals.
The decimals represent major, minor,

5 Semantic Versioning: https://semver.org

and patch versions in that order. So a 1.2.5 release indicates major version 1, minor version 2, and patch version

This tells our users anyone currently
running 1.2.x should be safe to upgrade
without breaking anything. Users who
are currently using 1.x.x can see the
new release has a few minor changes
they may need to review. If we have
any users using 0.x.x then the 1.2.5 tells
them there are breaking changes from
their current version and likely need to
update their application to support our
new version.
The guide I like to use when deter-
mining what my next version number
will be is somewhat straightforward
but can still be subjective. I always
choose to bump a minor version even
if I’m not sure it’s justified. I bump the
patch version if there are changes to
files in the repository that don’t affect
how my library functions, such as
updating a README or another such file.
This new 1.2.5 release does not break
anything in 1.2.4 (or anything in 1.2).
If we update logic somewhere in our
library or change currently set behav-
ior, I would bump the minor version to
indicate there is a small change users
of the library should investigate before
upgrading. Never tag a minor release
which has a backward compatible
breaking change. Major versions are
precisely what you want to bump when
adding breaking changes.

Further simplifying the “what is our new version going to be” question, we can think about it in the context of our library users. We’re tagging 1.2.5, but if we have logic changes, we should probably bump the minor version so the release would be 1.3.0. If we added features but didn’t change anything else, we would also bump the minor version to indicate there has been a meaning- ful change to the functionality. Finally, when we have huge changes, bump up the minimum PHP version we support, or break backward compatibility, we’ll increment the major version to 2.0.0. This allows us to correct past mistakes while keeping the library in a usable state for any of our existing users while allowing them to understand how our library’s version affects their application. Tagging releases is a critical aspect of maintaining an open source library. It’s our job to ensure our users have a stable, tested version to use and they are clear on changes based on our use of Seman- tic Versioning in our releases.

Recap I have thoroughly enjoyed writing this three post series on producing packages. I hope you have found it valu- able and useful in your PHP libraries and packages.

Joe Ferguson is a PHP developer and community organizer. He is involved with many different technology related initia- tives in Memphis including the Memphis PHP User group. He’s been married to his extremely supportive and amazing wife for a really long time and she turned him into a crazy cat man. They live in the Memphis suburbs with their two cats. @JoePFerguson

Better Practice, Dec. 2018

Get our desktop app

Company

Features

Documentation

Resources