http://www.phparch.com \ December 2018 \ 37The Workshop
Producing Packages, Part Three
Joe Ferguson
Over the past two months we’ve been building PHP Easy Math a purposely simple example library
to demonstrate how to build a reusable package for the PHP ecosystem. Make sure to check the
previous issues if you’re just now joining us! This article is the third and final installment in this
series. We’re going to cover triaging and managing issues users may open as well as pull requests
to your library.How to Triage Issues
Issues are the primary way your
library users communicate their needs
and problems to you. It is your respon-
sibility to answer each issue promptly
with respect and tact. Always assume
the issue author is well-intentioned; if
you find yourself typing in all capitals,
maybe you should step away for a bit
before answering the issue. While you
don’t have to address every single issue
and you shouldn’t feel beholden to
users for free tech support, I always try
to respond to issues even if it’s to let the
author know it’s not something I can
help.
I try to triage issues as they come in
depending on what I’m working on at
the time. If they come in during normal
day job hours or if I know I won’t be
able to investigate in a timely manner
I often post a comment acknowledging
I see the issue and give a timeframe of
when I expect to be able to investigate.
This is a great way to show your users
you care about their issues and will
make time to investigate.Step 1: Review The Issue
Read through the entirety of the
issue and try not to make assumptions
or guess the solution. If the author has
included steps to reproduce, give them
a try and see if you can reproduce the
issue too.
If the issue is a duplicate, or if the
author is clearly doing something
wrong, be tactful in your response.
Link the user (in a peaceful tone) to the
related issues. Don’t reply with a “let me
google that for you” link; it’s not 2001
anymore, and you shouldn’t be a jerk.Step Two: Acknowledge and Document
If you’re able to reproduce the issue,
let the user know and start document-
ing your debug process. I typically do
this in the issue comments so it’s easy
to refer to the context of the debug-
ging or research. This may include
testing different versions, compati-
bilities, operating systems, and more.
Be thorough and patient during this
process. Communicate with the author
to ensure you’re both on the same page
and talking about the same things.
Research any error messages. Even if
the problem isn’t your libraries fault, it
may be helpful to other users who may
run into the same thing. If you do find
the issue is not with your package and
is caused by another package, comment
and update the author to let them know.
Share links to related issues and don’t be
afraid to open an issue on the upstream
repository if there isn’t already one
open.
Resolution
If the issue can be resolved, let the
author know the timeline of when they
can expect you to fix it. Feedback is a
great way to drive engagement in your
open source project. Don’t be afraid
to use tags on GitHub and mark the
issue “Needs Fixing” or “Help Wanted”
to encourage others to try to contrib-
ute a fix. I always like to inform the
user when they can expect to see a
change (e.g., the next release, the next
month when a release is scheduled, or
some other timeframe due to whatever
reasons may exist).
If you can’t fix the issue for whatever
reason, explain your reasoning andclose the issue. Closing the issue isn’t
the end, users can still comment on
closed issues but don’t close an issue
until you’re ready. I only close issues
when I’ve exhausted all known options,
checked with other developers for an
option, or otherwise have expended all
ideas for resolution.Issue Templates
If you have a standard set of questions
you need an issue author to answer, you
may want to consider using GitHub
issue and pull request templates^1. These
templates can display information for
the user to fill out such as PHP version,
operating system, library version, and
other factors. So you can get a better
idea of the circumstances and environ-
ment on which they’re experiencing
the issue. You can also use pull request
templates to do similar things like
providing a workflow checklist for the
pull request author to fill out to show
they’ve followed your established work-
fl ow.
In the Laravel Homestead^2 repository,
I leverage issue templates to collect
several data points from users such as:- Vagrant version
- Homestead version
- Vagrant provider version
- logs of commands and expected
results and actual results
This practice allows me to easily
skim through issues and quickly iden-
tify version incompatibilities, common
1 issue and pull request templates:
https://phpa.me/github-issue-templates
2 Laravel Homestead:
http://github.com/laravel/homestead/