Releasing High Quality Packages - Longhorn PHP 2021
•0 likes•168 views
Report
Share
Download to read offline
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.
More Related Content
What's hot
What's hot(20)
Similar to Releasing High Quality Packages - Longhorn PHP 2021
![Releasing High-Quality Packages - php[world] 2018](https://cdn.slidesharecdn.com/ss_thumbnails/bz5wyzkrrzegldtwykqa-signature-3670eb77c491cb71535d0b3a90e09135651d8fc4e9572397ec836478d39deed5-poli-181114191507-thumbnail.jpg?width=384&fit=bounds)
Similar to Releasing High Quality Packages - Longhorn PHP 2021(20)
![Releasing High-Quality Packages - php[world] 2018](https://cdn.slidesharecdn.com/ss_thumbnails/bz5wyzkrrzegldtwykqa-signature-3670eb77c491cb71535d0b3a90e09135651d8fc4e9572397ec836478d39deed5-poli-181114191507-thumbnail.jpg?width=768&fit=bounds)
More from Colin O'Dell
![Automating Deployments with Deployer - php[world] 2018](https://cdn.slidesharecdn.com/ss_thumbnails/xamdmkcnqmmivllu5fr0-signature-d28101e5fa1800496725871fd6e41c7ab64bce1a21924d6067b898d91419f1b9-poli-181115151019-thumbnail.jpg?width=384&fit=bounds)
More from Colin O'Dell(20)
![Automating Deployments with Deployer - php[world] 2018](https://cdn.slidesharecdn.com/ss_thumbnails/xamdmkcnqmmivllu5fr0-signature-d28101e5fa1800496725871fd6e41c7ab64bce1a21924d6067b898d91419f1b9-poli-181115151019-thumbnail.jpg?width=768&fit=bounds)
![Automating Your Workflow with Gulp.js - php[world] 2016](https://cdn.slidesharecdn.com/ss_thumbnails/1hdltk6qyioyapbnbsuw-signature-ffa82ea34fcd60983c97ee8b9ba271b32b08a69dc912d673db21bd57dfcf8768-poli-161117191138-thumbnail.jpg?width=768&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=768&fit=bounds)
Recently uploaded
Recently uploaded(20)
Releasing High Quality Packages - Longhorn PHP 2021
- 2. @colinodell @colinodell PHP League Leadership Team Maintainer of popular packages: league/commonmark league/html-to-markdown colinodell/json5 Colin O'Dell Principal Engineer at Unleashed Technologies
- 3. @colinodell What Are Packages? Reusable libraries; installed via Composer
- 5. @colinodell
- 6. @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
- 7. @colinodell PHP-FIG, PSR-0, & Composer 321,100 Packages on Packagist 3.1 million Unique Releases
- 8. @colinodell Package Benefits • Pre-written • Reusable • Community-maintained • Framework-agnostic • Easily installed • Robust dependency resolution
- 9. @colinodell Releasing Your Own Packages
- 10. @colinodell Overview Definition of Quality Project Structure Testing Packaging Releasing Ongoing Maintenance Development Best Practices
- 11. @colinodell
- 12. @colinodell Definition of Quality Semantically Versioned Actively Maintained User Friendly Composer Installable Extensively Documented S A U C E
- 15. @colinodell Project & Vendor Name There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
- 16. @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
- 17. @colinodell
- 19. @colinodell composer.json • Project dependencies • Include PHP version & extensions
- 20. @colinodell composer.json • Project dependencies • Include PHP version & extensions • Development dependencies
- 21. @colinodell composer.json • Project dependencies • Include PHP version & extensions • Development dependencies • Autoloading configuration • PSR-4, not PSR-0 • Separate namespace for tests
- 23. @colinodell Source Code • Minimal dependencies; wide constraint ranges • Make framework agnostic • Service providers for specific frameworks okay • Provide interfaces • Consistent coding style (PSR-2?) • Use community standards (PSRs) • Follow best practices and design principles
- 24. @colinodell Project Hosting Features: • Project downloads • Issue reporting • Pull requests / code reviews • Collaboration • CI integrations
- 25. @colinodell Testing Automating the testing process
- 27. @colinodell Unit Tests • Test individual components • PHPUnit – defacto standard • Aim for 80% code coverage
- 28. @colinodell
- 29. @colinodell Automated Tests • Not just unit tests: • Functional tests • Integration tests • Acceptance tests • Other good test frameworks: • Phpspec • Behat • Codeception • Don’t forget static analysis!
- 30. @colinodell Static Analysis Automated analysis of source code without executing the application Checks for: • Missing or incorrect type hints (param/return types and docblocks) • Type errors • Existence of methods and properties • Unnecessary/useless code • Correct argument types passed to (s)printf() • etc. Supports generics too!
- 36. @colinodell Continuous Integration • Run tests across all supported versions • PHPUnit • Check code style • PHPCS • Static code analysis • Psalm • PHPStan • Track code quality metrics • Scrutinizer CI
- 39. @colinodell
- 41. @colinodell Packaging Getting the code ready for distribution
- 42. @colinodell Licensing • Modifications • Distribution • Attribution • Commercial Use Permissive: MIT; BSD; ISC Prevent Closed Source: GPLv3; Mozilla Public License Documentation: Creative Commons
- 47. @colinodell Documentation: README.md • What problem your package solves • Installation steps • Configuration • Sample Usage • FAQs • Link to more comprehensive docs • Badges!
- 48. @colinodell Documentation: docblocks Benefits: • Read docs while coding • IDE auto-completion • Short description • Parameter types, names, and purposes • Return types • Any thrown exceptions
- 49. @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
- 50. @colinodell Archive Settings Package consumers (probably) don’t want: • Tests • Dev dependencies • Issue / PR templates • GitHub Actions configuration • Your .gitignore development settings • Images used in README
- 51. @colinodell Archive Settings - .gitattributes
- 56. @colinodell Semantic Versioning – semver.org 1.0.0 (stable) or 0.1.0 (unstable)
- 57. @colinodell Semantic Versioning – semver.org x . y . z Major . Minor . Patch
- 58. @colinodell Semantic Versioning – semver.org 2 . 4 . 5 Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 59. @colinodell 2 . 4 . 6 2 . 4 . 5 Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 60. @colinodell 2 . 5 . 0 2 . 4 . 5 Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 61. @colinodell 3 . 0 . 0 2 . 4 . 5 Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
- 62. @colinodell Semantic Versioning – semver.org 0 . x . y Major . Minor . Patch Any 0.x.y release may break backwards compatibility! My recommendation: treat X.Y as major.minor
- 64. @colinodell
- 65. @colinodell Upgrading Notes • Documentation on upgrading between major versions • Describe BC breaks • Provide instructions for users to update their code UPGRADE.md file or in site docs
- 66. @colinodell
- 72. @colinodell Ongoing Maintenance Addressing issues, handling PRs, and maintaining your community
- 73. @colinodell Maintainer Responsibilities •Be responsive! •Triage issues; keep queue clean •Review PRs & provide feedback •Share responsibility with core contributors
- 74. @colinodell CONTRIBUTING.md • Requirements • Considerations • Process • Tips
- 75. @colinodell Issue / PR Templates
- 76. @colinodell Issue / PR Templates
- 77. @colinodell Issue / PR Templates
- 78. @colinodell
- 79. @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/
- 80. @colinodell
- 81. @colinodell .editorconfig • Defines preferred indentation style and line breaks • Automatically configures contributor IDEs • Most major IDEs supported
- 82. @colinodell .gitignore Ensures certain files are never committed to Git
- 84. @colinodell Further Reading Additional information and resources on creating high-quality PHP packages
- 85. @colinodell Further Reading • https://github.com/thephpleague/skeleton • http://phppackagechecklist.com • https://getcomposer.org/doc/04-schema.md • https://packagist.org/?type=phpcodesniffer-standard • https://medium.com/bumble-tech/php-code-static-analysis-based-on-the- example-of-phpstan-phan-and-psalm-a20654c4011d • https://leanpub.com/principles-of-package-design
- 86. @colinodell Questions? Slides / Feedback: https://joind.in/talk/e81ae
- 87. @colinodell Thank you! Slides / Feedback: https://joind.in/talk/e81ae