Anatomy of a dope PHP package repository
While contributing to Construct, maintained by Jonathan Torres, I gathered some insights and learnings on the characteristics of a dope PHP package repository. This post summarises and illustrates these, so that PHP package develeopers have a complementary guideline to improve existing or imminent package repositories. Jonathan Reinink did a good job in putting the PHP package checklist out there which provides an incomplete, but solid quality checklist for open-source PHP packages.
I'll distill the characteristics of a dope PHP package repository by looking at the repository artifacts Construct can generate for you when starting the development of a new PHP project or micro-package. The following tree command output shows most of the elements this post will touch upon. The artifacts in parenthese are optional and configurable from Construct but can nonetheless have an import impact on the overall package quality.
├── <package-name> │ ├── CHANGELOG.md │ ├── (CONDUCT.md) │ ├── composer.json │ ├── composer.lock │ ├── CONTRIBUTING.md │ ├── (.editorconfig) │ ├── (.env) │ ├── (.env.example) │ ├── (.git) │ │ └── ... │ ├── .gitattributes │ ├── (.github) │ │ ├── CONTRIBUTING.md │ │ ├── ISSUE_TEMPLATE.md │ │ └── PULL_REQUEST_TEMPLATE.md │ ├── .gitmessage │ ├── .gitignore │ ├── (.lgtm) │ ├── LICENSE.md │ ├── (MAINTAINERS) │ ├── (.php_cs) │ ├── (phpunit.xml.dist) │ ├── README.md │ ├── (docs) │ │ └── index.md │ ├── src │ │ └── Logger.php │ ├── tests │ │ └── LoggerTest.php │ ├── .travis.yml │ ├── (Vagrantfile) │ └── vendor │ └── ...
Definition of a dope PHP package repository
Before jumping into the details, let's define what could be considered as a dope package repository. Therefor, being lazy, I'm going to simply reword this classic quote from Michael Feathers> Clean code is code that is written by someone who cares.to
> A dope PHP package repository is one that is created and maintained by someone who cares.
Artifact categories
The next shown pyramid illustrates the three main categories the artifacts of a package repository will fall into.
Second there's the configuration for a myriad of tools like Git, GitHub, EditorConfig, Composer, the preferred testing framework, the preferred continuous inspection / integration platform such like Scrutinizer or Travis CI, and so forth.
The final category includes tools which ease the life of maintainers and potential contributors equally. These tools can be helpful for releasing new versions, enforcing coding standard compliance, or commit message quality and consistency.
Consistency
Sourcecode
All sourcecode and accompanying tests or specs should follow a coding standard (PSR-2) and have a consistent formatting style, there's nothing new here. The perfect place to communicate such requirements is the CONTRIBUTING.md file.Tools like PHP Coding Standards Fixer or PHP_CodeSniffer in combination with a present configuration .php_cs|ruleset.xml.dist and a command wrapping Composer script are an ideal match to ease compliance. The Composer script cs-fix shown next will be available for maintainers and contributors alike.
composer.json
{
"__comment": "omitted other configuration",
"scripts": {
"cs-fix": "php-cs-fixer fix . -vv || true"
}
}
Consistent formatting styles like line endings, indentation style, and file encoding can be configured via an EditorConfig configuration residing in .editorconfig which will be used when supported by the IDE or text editor of choice.
Artifact naming and casing
Like sourcecode formatting and naming, repository artifacts should also follow a predictable naming scheme. All documentation files should have a consistent extension like .md or .rst and the casing should be consistent throughout the package repository. Comparing├── <package-name> │ ├── changelog.md │ ├── code_of_conduct.md │ ├── ... │ ├── .github │ │ └── ... │ ├── LICENSE │ ├── Readme.md │ ├── roadmap.rstto
├── <package-name> │ ├── CHANGELOG.md │ ├── CODE_OF_CONDUCT.md │ ├── ... │ ├── .github │ │ └── ... │ ├── LICENSE.md │ ├── README.md │ ├── ROADMAP.mdI would favour the later one anytime for it's much easier reading flow and pattern matchableness. The easier reading flow is achieved by the upper casing of the *.md files which also clearly communicates their documentation character.
The configuration files for tools which except the .dist file extension per default should all have such one like shown next.
├── <package-name> │ ├── build.xml.dist │ ├── phpunit.xml.dist │ ├── ruleset.xml.dist │ ├── ...
Commit message format
Next to the package's changelog, incrementally growing in the CHANGELOG.md file, the Git commit messages are an important source of change communication. Therefor they should also follow a consistent format which improves the reading flow while also leaving a professional impression. This format can be documented once again in the CONTRIBUTING.md file or even better be provided via a .gitmessage file residing in the package's Git repository.Once more a Composer script, named configure-commit-template here, can ease configuration and if configured Git will use it's content when committing without the -m|--message and -F|--file option.
composer.json
{
"__comment": "omitted other configuration",
"scripts": {
"configure-commit-template": "git config --add commit.template .gitmessage"
}
}To enforce commit message formatting adherence to the rules described by Chris Beams on a Git hook level, the git-lint-validators utility by Billie Thompson can be helpful.
Versioning
Release versions should follow the semantic versioning specification aka SemVer, once again there's nothing new here. When using version numbers in the sourcecode or CLI binaries, these should be in sync with the set Git tag. Tools like RMT or self-written tools should be utilised for this mundane task.The next shown code illustrates such a simple self-written tool named application-version. It's main purpose is to set the provided version number in the CLI application's binary and avoid an application version and Git tag mismatch.
bin/application-version
#!/usr/bin/env php
<?php
$binApplicationName = '<bin-application-name>';
$binFile = __DIR__ . DIRECTORY_SEPARATOR . $binApplicationName;
list($void, $binFileRelative) = explode($binApplicationName, $binFile, 2);
$shortBinFilePath = $binApplicationName . $binFileRelative;
$options = getopt('v:ch', ['version:', 'current', 'verify-tag-match', 'help', 'current-raw']);
$help = <<<HELP
This command sets the version number in the {$shortBinFilePath} file:
Usage:
application-version [options]
Options:
-c, --current, --current-raw The current version number
--verify-tag-match Verify application version and Git tag match
-v, --version The version number to set
-h, --help Display this help message
HELP;
if (array_key_exists('h', $options) || array_key_exists('help', $options)) {
echo $help;
exit(0);
}
/**
* Return the application version.
*
* @param string $binFile File holding the application version.
* @return string
*/
function get_application_version($binFile) {
$matches = [];
$match = preg_match(
'/(\d+\.)?(\d+\.)?(\*|\d+)/',
file_get_contents($binFile),
$matches
);
return trim($matches[0]);
}
/**
* Return latest tagged version.
*
* @return string
*/
function get_latest_tagged_version() {
exec('git describe --tags --abbrev=0', $output);
return trim($output[0]);
}
if (array_key_exists('verify-tag-match', $options)) {
$applicationVersion = 'v' . get_application_version($binFile);
$latestGitTag = get_latest_tagged_version();
if ($applicationVersion === $latestGitTag) {
echo "The application version and Git tag match on {$latestGitTag}." . PHP_EOL;
exit(0);
}
echo "The application version {$applicationVersion} and Git tag {$latestGitTag} don't match." . PHP_EOL;
exit(1);
}
if (array_key_exists('current-raw', $options)) {
echo get_application_version($binFile) . PHP_EOL;
exit(0);
}
if (array_key_exists('c', $options) || array_key_exists('current', $options)) {
$applicationVersion = 'v' . get_application_version($binFile);
$latestGitTag = get_latest_tagged_version();
echo "Current version set in {$shortBinFilePath} is {$applicationVersion}." . PHP_EOL;
echo "Current tagged version {$latestGitTag}." . PHP_EOL;
exit(0);
}
if ($options === []) {
echo 'No options set.' . PHP_EOL;
exit(1);
}
$version = isset($options['version']) ? trim($options['version']) : trim($options['v']);
$fileContent = file_get_contents($binFile);
$fileContent = preg_replace(
'/(.*define.*VERSION.*)/',
"define('VERSION', '$version');",
$fileContent
);
file_put_contents($binFile, $fileContent);
echo "Set version in {$shortBinFilePath} to {$version}." . PHP_EOL;
exit(0);
The application-version tool could further be utilised in Travis CI builds, to avoid the earlier mentioned version differences, like shown in the next .travis.yml diggest. On an application version and Git tag mismatch the shown build script will break the build early..travis.yml
language: php # omitted other configuration script: # Verify application version and Git tag match - php bin/application-version --verify-tag-match # omitted other scripts
Lean builds
To speed up continuous integration builds, resource and time consuming extensions like Xdebug should be disabled when not required for measuring code coverage. The next shown before_script, tailored for Travis CI, is generated by Construct per default and might shave off a few build seconds and thereby provide a faster feedback..travis.yml
language: php # omitted other configuration before_script: - phpenv config-rm xdebug.ini || true # omitted other before_scriptsTo reduce email traffic, the email notifications send by Travis CI should be reduced to a minimum like shown next, or dependent on your workflow the could be disabled at all.
.travis.yml
language: php
# omitted other configuration
notifications:
email:
on_success: never
Something I really would love to be supported by Travis CI is a feature to ignore a set of definable artifacts which could be configured in a .buildignore file or the like. This way wording or spelling changes on non build relevant artifacts like the README.md wouldn't trigger a build and misspend resources and energy. There's a related GitHub issue and here's hope it will be revisited in the near future.
Lean releases
To keep releases (or dists in Composer lingo) of PHP projects or micro-packages as lean as possible, their repositories should contain a complete and valid .gitattributes file. With such a file present all export-ignored files will be excluded from release archives and thereby save a significant amount of bandwith and energy.The next code shows the content of such a .gitattributes file excluding non release relevant files like internal tools, configuration, and documentation artifacts. If for some reasons you require the complete source of a PHP project or micro-package you can bypass the default by using Composer's --prefer-source option.
.gitattributes
* text=auto eol=lf .editorconfig export-ignore .gitattributes export-ignore .github/ export-ignore .gitignore export-ignore .gitmessage export-ignore .php_cs export-ignore .travis.yml export-ignore bin/application-version export-ignore bin/release-version export-ignore bin/start-watchman export-ignore CHANGELOG.md export-ignore LICENSE.md export-ignore phpunit.xml.dist export-ignore README.md export-ignore tests/ export-ignoreTo validate the .gitattributes file of a PHP project or micro-package on the repository, Git HEAD, or build level the LeanPackageValidator CLI can be helpful.
Avoid badge posing
Badges, if used sparsely, are a handy tool for visualising some of the repository properties. It's definitely nice to immediately see the required PHP version, the current build status, or the latest version of the package as they save you manual look ups.Badges showing the amount of downloads, code coverage, or the chosen license are in my opinion kind of poserish, they cause unnecessary requests to the badge service, and are in case of the license even obsolete.
Why should you care about the dopeness of a PHP package repository?
Creating and maintaining a dope PHP package repository might have a positive impact on several levels. It can earn you some valuable Brownie points or even provide a conversation gambit when doing job interviews, simply because you showcase professionalism.Furthermore it's more likely to get valuable and high quality contributions from your second target audience when supportive documentation and tooling for things like issue creation, coding standards compliance, or Git commit message consistency are available.
It also might convince an end user, your main target audience, in using your package over a competitive one.
Le fini
So these were my recent insights and learnings on the anatomy of a dope PHP package repository. If you'r lucky to be attending this year's ZendCon, I recommend to catch Matthew Weier O'Phinney's session about Creating PHPantastic packages. I definitely be waiting for the related slides.Happy packaging.
No comments:
Post a Comment