Validating and Releasing Packages with Producer

Joe • March 29, 2016

php

Just the Fax

Producer is a pretty neat project that wants you to release higher quality packages.

Well, actually (sorry) it's "a command-line tool to validate, and then release, your PHP library package. It supports Git and Mercurial for version control, as well as Github, Gitlab, and Bitbucket for remote origins."

Background Noise

I was immediately interested in this tool because the Phergie project I manage (with other awesome developers) contains a number of individual packages. Some background on Phergie: she is an IRC bot that can do all sorts of things such as respond to commands and perform google searches, look up stock photo images, check the weather, and even flip a string of characters when asked. Each one of these abilities comes from a plugin package. Each one of these plugins can be used alone or in concert with any number of other plug ins. Managing these packages can be quite tedious and time consuming. One of the pain points I've quickly realized in ensuring all the informational files are kept up to date. Files such as the license, contributing, changes, etc. Some of these files are just missing from Phergie packages.

Phergie packages are pretty solid. We have Travis CI running our tests across multiple PHP versions, we have hours and hours into these packages. But I wanted to take it to the next level, step up our game so to speak. In order to help raise our quality control on our packages I needed a producer. (Did you see what I did there? I'm so sorry.)

My first plug in contribution to the Phergie ecosystem came in the form of a plugin that would fetch an excuse and return it into the channel. I'm a huge fan of the bastard operator from hell (BOFH) character and one of the plug ins on the wishlist was one that would return BOFH excuses to the IRC channel. I knocked out this plugin fairly quickly with some help from Elazar and WyriHaxmius who both know a lot more than I do when it comes to Phergie internals and thus phergie/phergie-irc-plugin-react-bofh was born.

Let's Do This Thing

The first step in doing anything with Producer is obviously installing it. I won't bore you with the details, but instead nudge you into the direction.

I started out just trying to validate the package. I needed to know how far off I was from where Producer wanted me to be. The initial problem I ran into was that Producer was using my globally installed version of PhpUnit instead of the version we're including with each package. Because we still support PHP 5.5.x with Phergie, we have to use PhpUnit 4.8.x. I pinged Paul via Twitter and said "ZOMFG THIS IS BROKEN" and he calmly replied "Dude, check out the norequire branch". As it would turn out this branch did solve my issue and uses the PhpUnit in the "vendor/bin/" folder instead of my global version.

Validate Your Package

Now I was able to run `producer validate 3.0.0` where `3.0.0` was the latest version of my `phergie/phergie-irc-plugin-react-bofh` package.

$ producer validate 3.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                                   
> git pull
< Already up-to-date.
> git push
Everything up-to-date
> git status -- porcelain
> composer validate
You are running composer with xdebug enabled. This has a major impact on runtime performance. See https://getcomposer.org/xdebug
< ./composer.json is valid
Validating phergie/phergie-irc-plugin-react-bofh 3.0.0
The LICENSE copyright year looks out-of-date or is a date range.
> composer update
You are running composer with xdebug enabled. This has a major impact on runtime performance. See https://getcomposer.org/xdebug
Loading composer repositories with package information
Updating dependencies (including require-dev)
Nothing to install or update
Generating autoload files
> phpunit
< PHPUnit 5.2.12 by Sebastian Bergmann and contributors.
<
< ...                                                                4 / 4 (100%)
<
< Time: 57 ms, Memory: 6.00Mb
<
< OK (4 tests, 12 assertions)
> git status -- porcelain
> rm -rf /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/tmp/phpdoc
> phpdoc -d src/ -t /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/tmp/phpdoc -- force -- verbose -- template=xml
< Collecting files .. OK
< Initializing parser .. OK
< Parsing files
< Parsing /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/src/Plugin.php
<   No summary for method getSubscribedEvents()
<   Argument $event is missing from the Docblock of handleBofhCommand
<   Argument $queue is missing from the Docblock of handleBofhCommand
<   No summary for method handleBofhCommand()
<   Argument $event is missing from the Docblock of handleBofhHelpCommand
<   Argument $queue is missing from the Docblock of handleBofhHelpCommand
<   No summary for method handleBofhHelpCommand()
<   Argument $event is missing from the Docblock of fetchExcuse
<   Argument $queue is missing from the Docblock of fetchExcuse
<   No summary for method fetchExcuse()
< Storing cache in "/Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/tmp/phpdoc" .. OK
< Load cache                                                         ..    0.000s
< Preparing template "xml"                                           ..    0.013s
< Preparing 1 transformations                                        ..    0.000s
< Build "elements" index                                             ..    0.000s
< Replace textual FQCNs with object aliases                          ..    0.001s
< Resolve @link and @see tags in descriptions                        ..    0.000s
< Enriches inline example tags with their sources                    ..    0.000s
< Build "packages" index                                             ..    0.002s
< Build "namespaces" index and add namespaces to "elements"          ..    0.000s
< Collect all markers embedded in tags                               ..    0.000s
< Transform analyzed project into artifacts                          ..
< Applying 1 transformations
<   Initialize writer "phpDocumentor\Plugin\Core\Transformer\Writer\Xml"
<   Execute transformation using writer "xml"
<    0.018s
< Analyze results and write report to log                            ..    0.000s
  Expected class-level @package phergie/phergie-irc-plugin-react-bofh, actual @package Phergie\Irc\Plugin\React\BOFH, in class \Phergie\Irc\Plugin\React\BOFH\Plugin
Docblocks do not appear valid.

So the bit of that we're most interested in at the moment is this bit:

< Parsing /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/src/Plugin.php
<   No summary for method getSubscribedEvents()
<   Argument $event is missing from the Docblock of handleBofhCommand
<   Argument $queue is missing from the Docblock of handleBofhCommand
<   No summary for method handleBofhCommand()
<   Argument $event is missing from the Docblock of handleBofhHelpCommand
<   Argument $queue is missing from the Docblock of handleBofhHelpCommand
<   No summary for method handleBofhHelpCommand()
<   Argument $event is missing from the Docblock of fetchExcuse
<   Argument $queue is missing from the Docblock of fetchExcuse
<   No summary for method fetchExcuse()

Looks like we're missing various summaries and docblocks from our Plugin file.

Updating to fix the "No summary for method getSubscribedEvents()" message.

Before:

/**
     *
     *
     * @return array
     */
    public function getSubscribedEvents()

After:

/**
     *  Return subscribed events
     *
     * @return array
     */
    public function getSubscribedEvents()

Updating to fix the "Argument $event is missing from the Docblock of handleBofhCommand" message.

Before:

/*
    * @param \Phergie\Irc\Plugin\React\Command\CommandEventInterface $event
    * @param \Phergie\Irc\Bot\React\EventQueueInterface $queue
    */
    public function handleBofhCommand(Event $event, Queue $queue)

After:

/**
* Process the command
* @param Event $event
* @param Queue $queue
*/
public function handleBofhCommand(Event $event, Queue $queue)

Hopefully you get the idea of the sort of things we were having to fix in regards to the phpdoc output.

The next problem I ran into was the fact that I previously had no `CHANGES.md` file in the repo so the output was complaining about the fact that my file was blank:

...
Checking if CHANGES up to date.
> git log -1 CHANGES.md
< commit 133fc6896474ba1fc78bbe9b61d67328d3bda45d
< Author: Joe Ferguson <joe@joeferguson.me>
< Date:   Mon Mar 28 17:38:35 2016 -0500
<
<     Adding CHANGES.md file
CHANGES date is Mon Mar 28 17:38:35 2016 -0500.
> git log -1
< commit 7e3cb6733d8926314bb591552db14b4f0f68de24
< Author: Joe Ferguson <joe@joeferguson.me>
< Date:   Mon Mar 28 19:03:34 2016 -0500
<
<     update docblocks and add missing docblocks and summary
...
Please update and commit the CHANGES.

I did some brief looking around at what other people do for their `CHANGES.md` file and ended up using this command to output the commits from my tag: `git log –pretty=format:"* %h -- %aN -- %s" 3.0.0 >` and I copied that into my CHANGES.md file.

Now that we have a somewhat respectable `CHANGES.md` file, We'll validate again to see what we have left to do:

$ producer validate 3.0.0                                                                                                                                                                                                                           
> git pull
< Already up-to-date.
> git push
Counting objects: 3, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 648 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To git@github.com:phergie/phergie-irc-plugin-react-bofh.git
   7e3cb67..1e9085f  master -> master
> git status -- porcelain
> composer validate
You are running composer with xdebug enabled. This has a major impact on runtime performance. See https://getcomposer.org/xdebug
< ./composer.json is valid
Validating phergie/phergie-irc-plugin-react-bofh 3.0.0
> composer update
You are running composer with xdebug enabled. This has a major impact on runtime performance. See https://getcomposer.org/xdebug
Loading composer repositories with package information
Updating dependencies (including require-dev)
Nothing to install or update
Generating autoload files
> /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/vendor/bin/phpunit
< PHPUnit 4.8.24 by Sebastian Bergmann and contributors.
<
< ...
<
< Time: 228 ms, Memory: 6.00Mb
<
< OK (4 tests, 12 assertions)
> git status -- porcelain
> rm -rf /var/folders/5r/06h4xkxs3dx9p611w11pb7h40000gn/T/phpdoc/phergie/phergie-irc-plugin-react-bofh
> phpdoc -d src/ -t /var/folders/5r/06h4xkxs3dx9p611w11pb7h40000gn/T/phpdoc/phergie/phergie-irc-plugin-react-bofh -- force -- verbose -- template=xml
< Collecting files .. OK
< Initializing parser .. OK
< Parsing files
< Parsing /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/src/Plugin.php
< Storing cache in "/private/var/folders/5r/06h4xkxs3dx9p611w11pb7h40000gn/T/phpdoc/phergie/phergie-irc-plugin-react-bofh" .. OK
< Load cache                                                         ..    0.000s
< Preparing template "xml"                                           ..    0.009s
< Preparing 1 transformations                                        ..    0.000s
< Build "elements" index                                             ..    0.000s
< Replace textual FQCNs with object aliases                          ..    0.001s
< Resolve @link and @see tags in descriptions                        ..    0.000s
< Enriches inline example tags with their sources                    ..    0.000s
< Build "packages" index                                             ..    0.000s
< Build "namespaces" index and add namespaces to "elements"          ..    0.000s
< Collect all markers embedded in tags                               ..    0.000s
< Transform analyzed project into artifacts                          ..
< Applying 1 transformations
<   Initialize writer "phpDocumentor\Plugin\Core\Transformer\Writer\Xml"
<   Execute transformation using writer "xml"
<    0.005s
< Analyze results and write report to log                            ..    0.000s
Checking if CHANGES up to date.
> git log -1 CHANGES.md
< commit 1e9085f03e363dc4a292b58266e41a1e729bd4aa
< Author: Joe Ferguson <joe@joeferguson.me>
< Date:   Mon Mar 28 21:39:38 2016 -0500
<
<     Update changes
CHANGES date is Mon Mar 28 21:39:38 2016 -0500.
> git log -1
< commit 1e9085f03e363dc4a292b58266e41a1e729bd4aa
< Author: Joe Ferguson <joe@joeferguson.me>
< Date:   Mon Mar 28 21:39:38 2016 -0500
<
<     Update changes
Last commit date is Mon Mar 28 21:39:38 2016 -0500.
CHANGES appears up to date.
No open issues.
phergie/phergie-irc-plugin-react-bofh 3.0.0 appears valid for release!

Hey! We appear to have a valid release!

Release the Krak...Package!

Now that we have some changes we'd like to tag, why Don't we use producer to push out a new release:

$ producer release 3.0.1                                                                                                                                                                                                                            
THIS WILL RELEASE THE PACKAGE.
> git pull
< Already up-to-date.
> git push
Everything up-to-date
> git status -- porcelain
> composer validate
You are running composer with xdebug enabled. This has a major impact on runtime performance. See https://getcomposer.org/xdebug
< ./composer.json is valid
Validating phergie/phergie-irc-plugin-react-bofh 3.0.1
> composer update
You are running composer with xdebug enabled. This has a major impact on runtime performance. See https://getcomposer.org/xdebug
Loading composer repositories with package information
Updating dependencies (including require-dev)
Nothing to install or update
Generating autoload files
> /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/vendor/bin/phpunit
< PHPUnit 4.8.24 by Sebastian Bergmann and contributors.
<
< ...
<
< Time: 124 ms, Memory: 6.00Mb
<
< OK (4 tests, 12 assertions)
> git status -- porcelain
> rm -rf /var/folders/5r/06h4xkxs3dx9p611w11pb7h40000gn/T/phpdoc/phergie/phergie-irc-plugin-react-bofh
> phpdoc -d src/ -t /var/folders/5r/06h4xkxs3dx9p611w11pb7h40000gn/T/phpdoc/phergie/phergie-irc-plugin-react-bofh -- force -- verbose -- template=xml
< Collecting files .. OK
< Initializing parser .. OK
< Parsing files
< Parsing /Users/halo/PhpstormProjects/phergie-irc-plugin-react-bofh/src/Plugin.php
< Storing cache in "/private/var/folders/5r/06h4xkxs3dx9p611w11pb7h40000gn/T/phpdoc/phergie/phergie-irc-plugin-react-bofh" .. OK
< Load cache                                                         ..    0.000s
< Preparing template "xml"                                           ..    0.010s
< Preparing 1 transformations                                        ..    0.000s
< Build "elements" index                                             ..    0.000s
< Replace textual FQCNs with object aliases                          ..    0.001s
< Resolve @link and @see tags in descriptions                        ..    0.000s
< Enriches inline example tags with their sources                    ..    0.000s
< Build "packages" index                                             ..    0.001s
< Build "namespaces" index and add namespaces to "elements"          ..    0.000s
< Collect all markers embedded in tags                               ..    0.000s
< Transform analyzed project into artifacts                          ..
< Applying 1 transformations
<   Initialize writer "phpDocumentor\Plugin\Core\Transformer\Writer\Xml"
<   Execute transformation using writer "xml"
<    0.007s
< Analyze results and write report to log                            ..    0.000s
Checking if CHANGES up to date.
> git log -1 CHANGES.md
< commit 1e9085f03e363dc4a292b58266e41a1e729bd4aa
< Author: Joe Ferguson <joe@joeferguson.me>
< Date:   Mon Mar 28 21:39:38 2016 -0500
<
<     Update changes
CHANGES date is Mon Mar 28 21:39:38 2016 -0500.
> git log -1
< commit 1e9085f03e363dc4a292b58266e41a1e729bd4aa
< Author: Joe Ferguson <joe@joeferguson.me>
< Date:   Mon Mar 28 21:39:38 2016 -0500
<
<     Update changes
Last commit date is Mon Mar 28 21:39:38 2016 -0500.
CHANGES appears up to date.
No open issues.
phergie/phergie-irc-plugin-react-bofh 3.0.1 appears valid for release!
Releasing phergie/phergie-irc-plugin-react-bofh 3.0.1
> git rev-parse -- abbrev-ref HEAD
< master
> git pull
From github.com:phergie/phergie-irc-plugin-react-bofh
 * [new tag]         3.0.1      -> 3.0.1
< Already up-to-date.
> git push
Everything up-to-date
> git status -- porcelain
Released phergie/phergie-irc-plugin-react-bofh 3.0.1 !

And we have released another version out into the wild!

Recap

Producer checks for a lot of different things. Producer wants to make sure you are releasing the best possible package you can. I learned a few tricks and "oh, THAT is why you do that" things in this process and I feel like there is a ton of value here for package maintainers to streamline their process or find that *one* thing that could help make their packages better.

Give it a shot for yourself, let me know how it works for you.

Thanks for reading.

Joe Ferguson