The Joel Test Redux: web2project

In the last few months or so, it appears the PHP Community has finally found the Joel TestLorna Jane spoke about it last month at PHPNW 09 and this week Brandon Savage adapted it for web development.  While I’d love to point out the fact that I’ve been writing about the Joel Test for years and even have the “Joel On Software” book on the required reading list for Blue Parabola staff… but I digress…

While all the rules are important in some way, there’s one we’ve taken to heart recently within web2project:

Can you make a shippable version of your software in one step?

Previously, to make a release, we had to:

  1. tag our release
  2. run all of our final install/smoke tests
  3. export from Subversion
  4. run one final phplint check
  5. generate a Changelog
  6. remove the Unit Tests (we don’t ship them)
  7. create the tar.gz and zip files and
  8. upload the files to Sourceforge

If we forgot a step, it wasn’t necessarily terrible, but it increased the risk that any number of issues could creep into the release.  So this summer after we had a few Unit Tests – thanks to Trevor Morse – I started on following this rule in our own operations.  You can view the progression of our Phing build.xml script on Sourceforge.  While there are literally a 100 things we could do through Phing – and more if we throw in some shell or php scripts – there are a handful of things we’re focused on.

First, we needed a simple way to run our Unit Tests. Running Unit Tests by hand is a pain, it introduces opportunities for dumb little mistakes that shouldn’t happen.  Even more importantly, we needed to make them simple for people who don’t want or care to learn the intricacies of the system.  And yes, we have documentation on running web2project’s Unit Tests.

Next, since we can’t install a phplint check as a pre-commit hook, we added it to this script. This ensures that we’re not distributing anything that is syntactically wrong.  This runs primarily when we package the code for a release, but can be run at any time.

Next, our Changelog was always mediocre at best. Thanks to some tips from fellow team member Bruce Bodger, we added a simple “svn log” statement to generate a complete Changelog.  Yes, this is a little tweak which is probably irrelevant in the bigger picture, but it’s one less thing we have to do manually.

Next, we implemented a simple CodeSniffer check. I’ve been a fan of CodeSniffer for years and to get it in place for web2project is handy for all of our purposes.  We’re not 100% within spec, but we’re getting progressively closer with each update and refactoring.

Finally, I stuck a simple command line user interface on the whole thing. After we tag the release, we can simple feed the tag name into the packager and the Phing script does the rest.  As a result of this script, now this is our process:

  1. tag our release
  2. run all of our final install/smoke tests
  3. run: phing package (choose the tag from above) and
  4. upload the files to Sourceforge

Overall the process is easier, faster, and has significantly less room for error.  If you’re interested in exploring and utilizing our build.xml script, please feel free… just remember to attribute it appropriately.  :)

And for the record, on the Joel Test, web2project is a solid 6 and a “sort of” on 3 others.  Pretty good for an Open Source project…

Are you interested in API Design? Check out our new book "A Pragmatic Approach to API Design." In it, we cover the basics on why you might need an API, how to get started on modeling your API, and finally some design patterns and anti-patterns to be aware of. Available soon from LeanPub