Releasing High Quality PHP Packages - ConFoo Montreal 2019
Download as PPTX, PDF1 like630 views
Releasing open-source libraries is more than sharing your Github URL with the world. There are many considerations and steps involved especially for successful and long-lived projects. In this talk we’ll cover the principles behind creating, releasing and maintaining high-quality libraries. Topics will include structuring the repository, implementing modern PHP standards, maintaining changelogs, using CI tests, releasing new versions and more.
![Releasing High-Quality Packages - php[world] 2018](https://cdn.slidesharecdn.com/ss_thumbnails/bz5wyzkrrzegldtwykqa-signature-3670eb77c491cb71535d0b3a90e09135651d8fc4e9572397ec836478d39deed5-poli-181114191507-thumbnail.jpg?width=560&fit=bounds)
Ad
More Related Content
What's hot (20)
Similar to Releasing High Quality PHP Packages - ConFoo Montreal 2019 (20)
![[WSO2Con EU 2017] Continuous Integration, Delivery and Deployment: Accelerate...](https://cdn.slidesharecdn.com/ss_thumbnails/ac4xwgqvrdkrwtftk7e7-signature-dbac0dc010ea0ff3c90449ac7a4aa2ad1e9d36fce7d438c08edba1852dade946-poli-171106125022-thumbnail.jpg?width=560&fit=bounds)
![Automating Deployments with Deployer - php[world] 2018](https://cdn.slidesharecdn.com/ss_thumbnails/xamdmkcnqmmivllu5fr0-signature-d28101e5fa1800496725871fd6e41c7ab64bce1a21924d6067b898d91419f1b9-poli-181115151019-thumbnail.jpg?width=560&fit=bounds)
Ad
More from Colin O'Dell (20)
![Automating Your Workflow with Gulp.js - php[world] 2016](https://cdn.slidesharecdn.com/ss_thumbnails/1hdltk6qyioyapbnbsuw-signature-ffa82ea34fcd60983c97ee8b9ba271b32b08a69dc912d673db21bd57dfcf8768-poli-161117191138-thumbnail.jpg?width=560&fit=bounds)
![Rise of the Machines: PHP and IoT - php[world] 2016](https://cdn.slidesharecdn.com/ss_thumbnails/2jzpbkqsquo5mxu7oudb-signature-8467784fc5aedfdbd5a9c94ce69651a7e0d34611ca4200017484ea2690e83d3c-poli-161116170421-thumbnail.jpg?width=560&fit=bounds)
![Hacking Your Way To Better Security - php[tek] 2016](https://cdn.slidesharecdn.com/ss_thumbnails/uqd0khzkrgkurabdbneg-signature-7dcd622b76c062c2eee3f98694b3b5ec21430a61a01fae765c25a1ac3086db5d-poli-160526150315-thumbnail.jpg?width=560&fit=bounds)
Ad
Recently uploaded (20)
![Download Wondershare Filmora Crack [2025] With Latest](https://cdn.slidesharecdn.com/ss_thumbnails/neo4j-howkgsareshapingthefutureofgenerativeaiatawssummitlondonapril2024-240426125209-2d9db05d-250419-250428115407-a04afffa-thumbnail.jpg?width=560&fit=bounds)
Releasing High Quality PHP Packages - ConFoo Montreal 2019
- 2. @colinodell@colinodell PHP League Leadership Team Maintainer of popular packages: league/commonmark league/html-to-markdown colinodell/json5 Colin O'Dell Lead Developer & DevOps Engineer Director of Technology at Unleashed Technologies
- 3. @colinodell What Are Packages? Reusable libraries; installed via Composer
- 5. @colinodell PHP-FIG, PSR-0, & Composer 2009: Framework Interoperability Group adopts PSR-0 autoloading standard 2011: Composer development begins 2012: Composer released with PSR-0 support Today: 213,660 Packages on Packagist 1.6 million Unique Releases
- 6. @colinodell Package Benefits • Pre-written • Reusable • Community-maintained • Framework-agnostic • Easily installed • Robust dependency resolution
- 7. @colinodell Releasing Your Own Packages
- 8. @colinodell Overview Definition of Quality Project Structure Testing Packaging Releasing Ongoing Maintenance Development Best Practices
- 9. @colinodell
- 10. @colinodell Definition of Quality Semantically Versioned Actively Maintained User Friendly Composer Installable Extensively Documented S A U C E
- 13. @colinodell Project & Vendor Name There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
- 14. @colinodell Project & Vendor Name PHP namespace = VendorNameProjectName Packagist repo = vendor-name/project-name • Choosing a name: • Available • Unique/memorable • Easy to search • Make names consistent
- 15. @colinodell
- 16. @colinodell composer.json • Project dependencies • Include PHP version & extensions • Development dependencies • Autoloading configuration • PSR-4 not PSR-0 • Separate namespace for tests
- 18. @colinodell Source Code • Minimal dependencies; wide constraint ranges • Make framework agnostic • Service providers for specific frameworks okay • Provide interfaces • Use community standards (PSRs) • Follow best practices and design principles • Consistent coding style (PSR-2?)
- 19. @colinodell Project Hosting Features: • Project downloads • Issue reporting • Pull requests / code reviews • Collaboration • CI integrations
- 20. @colinodell Testing Automating the testing process
- 22. @colinodell Unit Tests • Test individual components • PHPUnit – defacto standard • Aim for 80% code coverage
- 23. @colinodell
- 24. @colinodell Automated Tests • Not just unit tests: • Functional tests • Integration tests • Acceptance tests • Other good test frameworks: • Phpspec • Behat • Codeception • Use continuous integration!
- 27. @colinodell Continuous Integration • Run tests across all supported versions • Track code quality • Scrutinizer CI • Check code style • StyleCI • PHPCS
- 30. @colinodell
- 32. @colinodell Packaging Getting the code ready for distribution
- 33. @colinodell Licensing • Distribution • Attribution •Modifications •Commercial Use Permissive: MIT; BSD; ISC Prevent Closed Source: GPLv3; Mozilla Public License Documentation: Creative Commons
- 38. @colinodell Documentation: README.md • Badges • What problem your package solves • Installation steps • Sample Usage • Configuration
- 39. @colinodell Documentation: docblocks Benefits: • Read docs while coding • IDE auto-completion • Short description • Parameter types, names, and purposes • Return types • Any thrown exceptions
- 40. @colinodell Documentation: RTFM • Advanced usage or configuration • Additional code samples • Other functionality Where to host? • GitHub Pages • Jekyll • MkDocs • Other static site generator • readthedocs.org • Your own hosting
- 41. @colinodell Archive Settings Package consumers (probably) don’t want: • Tests • Dev dependencies • Issue / PR templates • Travis CI configuration • Your .gitignore development settings
- 42. @colinodell Archive Settings - .gitattributes
- 47. @colinodell Semantic Versioning – semver.org 1.0.0 (stable) or 0.1.0 (unstable)
- 48. @colinodell Semantic Versioning – semver.org x . y . zMajor . Minor . Patch
- 49. @colinodell Semantic Versioning – semver.org 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 50. @colinodell 2 . 4 . 6 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 51. @colinodell 2 . 5 . 0 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 52. @colinodell 3 . 0 . 0 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 53. @colinodell Semantic Versioning – semver.org 0 . x . yMajor . Minor . Patch Any 0.x.y release may break backwards compatibility! My recommendation: treat X.Y as major.minor
- 55. @colinodell
- 56. @colinodell UPGRADE.md • Documentation on upgrading between major versions • Describe BC breaks • Provide instructions for users to update their code
- 57. @colinodell
- 61. @colinodell Ongoing Maintenance Addressing issues, handling PRs, and maintaining your community
- 62. @colinodell Maintainer Responsibilities • Be responsive • Triage issues; keep queue clean • Review PRs & provide feedback • Share responsibility with core contributors
- 63. @colinodell CONTRIBUTING.md • Requirements • Considerations • Process • Tips
- 64. @colinodell Issue / PR Templates
- 65. @colinodell Issue / PR Templates
- 66. @colinodell Issue / PR Templates
- 67. @colinodell CODE_OF_CONDUCT.md • Expresses values and rules that contributors should adhere to • Promotes inclusion and contributions • Defines unacceptable behavior and enforcement • https://www.contributor-covenant.org/
- 68. @colinodell .editorconfig • Defines preferred indentation style and line breaks • Automatically configures contributor IDEs • Most major IDEs supported
- 69. @colinodell .gitignore Ensures certain files are never committed to Git
- 71. @colinodell Further Reading Additional information and resources on creating high-quality PHP packages
- 72. @colinodell Further Reading • https://github.com/thephpleague/skeleton • http://phppackagechecklist.com • https://getcomposer.org/doc/04-schema.md • https://leanpub.com/principles-of-package-design
Editor's Notes
- #3: I’m a member of the PHP League - We’re a group of developers dedicated to building high-quality packages for the PHP community Share our experience and best practice
- #4: --- Community-created bundle of code Provides useful functionality … It wasn’t always this easy
- #5: Virtually no interoperability
- #6: Framework Interoperability Group Autoloading eliminated need to manually require_once
- #7: Several benefits to having code available as a package … So you’ve got some code you want to release… (Maybe you want to pay it forward?) How would you do that?
- #8: More than just throwing code online
- #9: Packages and what makes them high-quality Look at structure of a quality package And the steps to prepare, release, and maintain your package
- #10: Everyone has their own definition Great staring point but not exhaustive
- #12: Look at quality through the lens of good project structure
- #13: This will serve as our checklist
- #15: Two parts: Vendor = person, group, company, or organization Project = individual package
- #17: (click once) 1. Meta info (click again) …
- #19: Logging: PSR-3 HTTP: PSR-7, 13, 15, 17 Caching: PSR-6, 16 Containers: PSR-11
- #23: “test bench”
- #26: Automatically runs tasks when: Code is pushed PR is created Code is merged New version is released Perfect for tests!
- #28: Run tests: Across all supported PHP versions Against future PHP versions Using minimal/older Composer constraints
- #37: Copyright Mention license
- #39: First impression
- #46: … At this point, Package is registered but not “released” – no versions available
- #50: Safe upgrading
- #51: Safe upgrading
- #52: Safe upgrading
- #53: Safe upgrading
- #54: Great for new libraries where architecture isn’t finalized
- #56: Added Changed Fixed Deprecated Removed