This article was originally published in php|architect in February 2009 and I published it mostly as it appeared in the magazine shy of the odd formatting to fit the blog format better.
Standards evolve all the time but this specific standard has not changed much at all since I wrote my article but as always for something written a year or two ago, take it with a pinch of salt :-)
—
PEAR has been around for many, many years, and thus has accumulated a lot of knowledge on how to run a large-scale project.
PEAR has run into countless hurdles along the way that had to be solved in one way or another. As a result of getting over these hurdles, we have produced good things that affect the whole PHP community and also things that well…let’s face it, didn’t help PEAR or PHP a whole lot.
But, how do we bring that experience from the knowledge bank of PEAR and give it back to the community, so other projects can learn from us and steer clear of what we did wrong and embrace what PEAR did right.
One of the things that really makes PEAR what it is today are the standards we have evolved for the past couple of years. A lot of other projects and even companies have embraced large chunks of those standards as their de facto standard for PHP userland code.
Just to name a few standards:
- Distribution system (channels, packages, package.xml)
- Coding Standards
- Version naming
- Directory layout
- Backwards Compatibility and what that entails
- And many others
If you want to read about the distribution system, you can grab the 2009 November and December issues of php|architect where I wrote about it in good detail, or you can wait for me to publish those on my blog.
Version Naming
Let’s start by talking about the version naming standard and why it’s important.
Now don’t get me wrong, it’s not like PEAR invented the need for version naming, be it for PHP projects or the software world at large, but the fact is that PEAR was one of the first, if not the first, large-scale PHP project that had more than one concurrent release at a time. This fact required a proper standard in the end.
So, almost 5 years ago today, the PEAR group at the time went ahead and formalized a standard to keep the version naming more consistent, yet still working with the version_compare function.
The document they produced can be accessed from http://pear.php.net/group/docs/20040226-vn.php, but I will attempt to simplify it a bit.
First, it’s important to understand that there is a difference between version numbers and version state and how they interact. Let’s look at how the basics of the version numbering system work. Consider x.y.z for a second, now let’s translate that into something human readable.
- x = Major release number
- y = Minor, used for feature additions
- z = patch level number, used when it’s purely
only a bug fix release
Now let’s have a quick look at the states, dev, alpha, beta, RC or stable (listed in the order of code maturity). So what you end up with is x.y.zstate (Note the lack of space there) except when you have a stable release. In PEAR, you might see version namings like so: 0.5.6alpha1, 0.12.0beta3, 1.0.0RC4, 1.2.0 and so on. With this system in mind, we need to see what each state and number incrementation really means for you and your project.
Quite often, I see people do their first release, and for some unknown reason, they decide that 0.0.1 is the best version, swear by it even. In the version naming standard we have in PEAR, that is not allowed because when you are releasing the first release you are not fixing bugs, you are adding new features, so the first release should always be 0.1.0, at the very least.
Something that happens fairly often as well is that people do their first release as 1.0.0 with a stable state, even though their project doesn’t truly have a stable API, such as, or even a stable product in general. Perhaps it’s because they believe they managed to get it very stable, but the fact is, no matter how stable you think your product is for the first release, always release the first one lower than 1.0.0 stable.
Keep in mind, when you go stable, stay stable! Don’t start messing up the API in a way that people will have to alter their applications, this tends to be called BC, or backwards compatibility.
Backwards Compatibility
Now what is backwards compatibility? In short, it is when I, as an application developer, pick library X to use in my application and pick release 1.2.0 to start utilizing the API of library X. Even though I don’t follow the development of library X, if they follow a proper, no-BC-breaking approach, then I should be able to upgrade the lib from 1.2.0 to 1.6.0 without having to change a single line
in my code. If a BC break would have occurred between 1.2.0 and 1.6.0, then there is a good chance that my application would stop working with such an upgrade. So BC breaks should only happen below stable, preferably only in the alpha state, if possible.
Food for Thought
So, I perhaps didn’t cover all that much of the version naming standard, but I do believe I got my point across and those interested in learning more can go to the link I supplied above to get a better idea of how this all works together beautifully.
A prime example of why it’s good to have a set standard on the version naming would be when Matthew Weier O’Phinney of Zend Framework fame contacted me in late 2008 to determine whether PEAR had this kind of standard. The Zend Framework team was having internal discussions in regards to version naming, especially for their preview releases, better known by other folks as alpha releases, where new api changes are introduced but still not considered stable or that an API could possibly break before the final release.
In the end, Matthew managed to convince them to use alpha/beta states on the package level while allowing them to use PR (Preview Release) for the website and announcements. This allows people to use version_compare on Zend Framework for future releases, potentially use a PEAR channel for distribution and to have proper stability states for what the release is supposed to reflect.
I felt like this was a very good example showing how using a well-established naming convention benefits the whole community and makes things a lot clearer for those familiar with said standards.
Hopefully this is as useful to you as it was to me and the projects of which I have been a part. It has, at least, been highly successful to PEAR and numerous other projects.
Helgi Þormar Þorbjörnsson 