The Joomla! Project is pleased to announce that we are (finally) ready to release an alpha version of the Joomla! Coding Standards which is compatible with PHP_CodeSniffer 2.x. In preparation for this release, we will be making some structural changes to our coding standards repository which may affect developers using this repository.
What are Coding Standards?
Coding standards help establish a common standard for how the code should be formatted and structured, helping to make it easier to read and maintain, especially when multiple developers are working on the same code base. In an Open Source project like Joomla! which has hundreds of contributors, this is something of paramount importance.
Branch Structure Changes
The first change which will be the most “disruptive” is that the current branch structure will change. Presently, there are two branches; `master` which holds the current PHP_CodeSniffer 1.x compatible ruleset and `phpcs-2` which is the target branch for the 2.x effort. Within the next couple of weeks we will be making the 2.x ruleset the `master` branch and the 1.x ruleset will be moved to a `1.x` branch. To facilitate this transition, the `1.x` branch has already been created.
Composer Availability
The 2.x ruleset is designed to be installable via Composer. Since registering the package will cause the full repo to be listed in Packagist, we will be looking at the efforts required to make the 1.x branch installable through Composer as well.
Proper Versioning
Historically, our coding standards repository has had no tagged versions; the instructions for using it have generally been to set up a git submodule pointing to the master branch. Going forward, we will begin tagging versions of the coding standards similar to how software packages are versioned.
Improved Management and Integration
During the upgrade to support PHP_CodeSniffer 2.x, several improvements have been made to our coding standard repository to make managing this resource easier going forward. Additionally, PHP_CodeSniffer 2.x offers several improvements which will assist developers with integrating and enforcing the standards.
Fixing Errors Automatically
One of the most exciting features coming with the 2.x ruleset is the ability to automatically fix many code style errors. Our custom sniffs in the coding standard have also added this autofixer ability. This one feature should be able to save developers and the Joomla! projects a great deal of time in ensuring code standard compliance without manually fixing things like line indenting.
Reduced Custom Sniffs
The 2.x ruleset also reduces the number of custom sniffs by implementing the included rules from PHP_CodeSniffer. This small change will reduce the effort needed to maintain our custom sniffs and ease the ability to migrate to future versions of PHP_CodeSniffer.
Unit Testing of Custom Sniffs
The 2.x ruleset also adds unit testing of the custom rules. This will help verify that any changes made will work as expected.
Selectively Applying Rules
Historically, our coding standards have been difficult to apply selectively for excluding 3rd party libraries, or for consideration of backwards compatibility items. Only limited ability for excluding rules and directories with 3rd party libraries was available from the PHP_CodeSniffer command line. Now with the 2.x ruleset, consuming packages can create their own project ruleset.xml rather than just directly using the Joomla! ruleset.xml. A project ruleset.xml allows the coding standard to be selectively applied for excluding 3rd party libraries, for consideration of backwards compatibility in existing projects, or for adjustments necessary for projects that do not need PHP 5.3 compatibility.
Thank You!
We would like to thank all of those involved in the PHPCS 2.x efforts, including Walt Sorensen who has spearheaded this massive undertaking.