Creating a Smooth Development Workflow for High-Quality Modular Open-Source PHP Libraries
•
1 like•1,136 views
Greg Anderson's slide deck from BADCamp 2016.
Having a fine-tuned continuous integration environment is extremely valuable, even for small projects. Today, there is a wide variety of standalone projects and online Software-As-A-Service offerings that can super-streamline your everyday development tasks that can help you get your projects up and running like a pro. In this session, we'll look at how you can get the most out of:
- GitHub source code repository
- Packagist package manager for Composer
- Travis CI continuous integration service
- Coveralls code coverage service
- Scrutinizer static analysis service
- Box2 phar builder
- PhpDocumentor api documentation generator
- ReadTheDocs online documentation reader service
- Composer scripts and projects for running local tests and builds
1 of 85
Download to read offline
More Related Content
Creating a Smooth Development Workflow for High-Quality Modular Open-Source PHP Libraries
1. Creating a Smooth Development
Workflow for High-Quality Modular
Open-Source PHP Libraries
by Greg Anderson
@greg_1_anderson
4. Pantheon.io
Use a PHP library from a module
{
"name": "drupal/lcache",
"description": "LCache module.",
"type": "drupal-module",
"license": "GPLv2",
"require": {
"lcache/lcache": "0.3.*"
}
}
● Add a minimal composer.json to module
○ n.b. Drupal 8 has an implicit
autoloader entry
Drupal/modulename
● Use Composer to manage Drupal site
○ drupal-composer/drupal-project
4
6. Pantheon.io
Focus of this Session
HOWEVER, we also need:
● Collaboration
● Reproducibility
● Analysis of
○ Test coverage
○ Code Quality
○ Open Source License Compliance
● Documentation
6
7. Pantheon.io
What is a smooth workflow?
Just push the
button, and the right
thing happens.
7
9. Pantheon.io
Is it worth the effort?
Also remember:
You will be able to respond to
high-priority requests faster.
Onboarding new team
members will be easier.
Consistent processes will lead
to consistent results and fewer
defects.
https://xkcd.com/1205/
9
10. Pantheon.io
Services to the rescue!
Collaborate with other engineers across multiple branches.
Keep a record of all work done.
Integrate With All Of The Things.
Run tests and
other tasks.
Calculate test
coverage.
Analyze code
complexity.
Track dependency
versions and licenses.
Package manager
for composer.
Publish documentation
site from markdown.
10
11. Pantheon.io
Follow the example of existing projects
Some projects we will examine:
● lcache/lcache
● consolidation/*
● westkingdom/website
http://dilbert.com/strip/1996-01-31
11
12. Pantheon.io
Github
● What can you do with it?
○ Collaborate through browser without git
○ Set up lots of integrations
● How do you use it effectively?
○ Add README and COLLABORATING
○ Make issue and PR templates
○ Advertise integrations with badges
● How do you fix mistakes?
https://github.com
12
17. Pantheon.io
Add a README
https://github.com/matiassingers/awesome-readme
● Short project description.
● Badges with links to services.
● Reasons for using project.
● Build and test instructions.
● Installation instructions.
● Usage documentation.
● How to contribute.
The README may either contain
this information directly, or contain
links to other documents where this
information can be found.
17
19. Pantheon.io
Add issue and PR templates
### Steps to reproduce
What did you do?
### Expected behavior
Tell us what should happen
### Actual behavior
Tell us what happens instead
### Overview
This pull request:
- [ ] Fixes a bug
- [ ] Adds a feature
- [ ] Breaks backwards compat
- [ ] Needs tests
### Description
Any additional information.
.github/pull_request_template.md.github/issue_template.md
19
20. Pantheon.io
Packagist
● What can you do with it?
○ Register projects so they may be easily
found
● How do you use it effectively?
○ Define a branch alias
○ Use search URLs to find projects of a
certain type (e.g. plugins)
https://packagist.org
20
32. Pantheon.io
Travis
● What can you do with it?
○ Run tests on multiple versions of PHP
○ Generate artifacts when tests pass
● How do you use it effectively?
○ Provide a functional phpunit.xml.dist
○ Test code style for PSR-2 conformance
○ Use composer install --prefer dist
○ Avoid testing PRs twice
○ Cache dependencies for faster builds
○ Commit composer.lock
○ Provide scripts to run tests locally
https://travis-ci.org
32
33. Pantheon.io
Set up phpunit.xml.dist
<phpunit bootstrap="vendor/autoload.php" colors="true">
<testsuites>
<testsuite name="annotation-command">
<directory prefix="test" suffix=".php">tests</directory>
</testsuite>
</testsuites>
</phpunit>
33
36. Pantheon.io
Test PRs only one time
branches:
# Only test the master branch and SemVer tags.
only:
- master
- /^[[:digit:]]+.[[:digit:]]+.[[:digit:]]+.*$/
36
45. Pantheon.io
Build status summary pages
Paste in badge image URLs
any place HTML can be
rendered (e.g. wiki pages) to
create summary pages.
45
46. Pantheon.io
Coveralls
● What can you do with it?
○ Keep a log of test coverage over time
○ See line-by-line what parts of the code are
tested, and what parts are not
● How do you use it effectively?
○ Periodically review untested functions, and
prioritize time to write new tests based on
importance
https://coveralls.io
46
55. Pantheon.io
Scrutinizer
● What can you do with it?
○ Analyze code for complexity and
duplication
○ Run tests and calculate coverage
(Travis and Coveralls better, though)
● How do you use it effectively?
○ Set up GitHub integration
○ Always fix reported “bugs”
○ Review “hot spots” and refactor
○ Learn from provided advice
○ Ignore advice you think is wrong
https://coveralls.io
55
56. Pantheon.io
Set up Scrutinizer GitHub Integration
Type the name of the
organization and project to
inspect; Scrutinizer will set
up the GitHub integration
for you.
56
62. Pantheon.io
Version Eye
● What can you do with it?
○ Track dependencies that have new versions
○ Confirm OSS license compliance
● How do you use it effectively?
○ Set up GitHub integration
○ Point your project’s license badge at the
VersionEye license overview page
https://www.versioneye.com
62
63. Pantheon.io
Set up license info in composer.json
{
"name": "consolidation/annotated-command",
"description": "Initialize Symfony Console commands …",
"license": "MIT",
"authors": [
{
"name": "Greg Anderson",
"email": "greg.1.anderson@greenknowe.org"
}
],
…
}
63
64. Pantheon.io
Set up VersionEye GitHub Integration
VersionEye will set up
the GitHub
integrations for your
project automatically;
just select your
project from a list.
64
66. Pantheon.io
Licenses tab
Spot licenses in the list
that are not like the
others.
n.b. Clicking on
patchwork/jsqueeze
reveals that it is
dual-licensed
Apache-2.0 / GPL-2
66
69. Pantheon.io
ReadTheDocs
● What can you do with it?
○ Publish documentation from
markdown files in source repository
● How do you use it effectively?
○ Set up GitHub integration
○ Link to your project documentation
from your project README page
https://readthedocs.org
69
76. Pantheon.io
Create simple API markdown docs
$ composer require victorjonsson/markdowndocs
$ vendor/bin/phpdoc-md phpdoc-md generate src > docs/api.md
$ git add docs/api.md
$ git commit -m "Add API documentation."
OH NO! It’s not automated!
● ReadTheDocs is a python service; it can’t run php.
● Can’t easily build from Travis and commit back to the
repository, as that would create a separate commit (not
part of the release, might cause another test run, etc.)
76
77. Pantheon.io
GitHub pages
● What can you do with it?
○ Serve static html directly from GitHub
○ Automatically update generated
documentation from Travis
● How do you use it effectively?
https://pages.github.com
All sorts of advanced techniques possible!
77