Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Releasing High-Quality Packages - php[world] 2018

111 views

Published on

Releasing open-source libraries involves much more than sharing your Github URL with the world. There are many considerations and steps involved, especially if you want your project to be successful and long-lived. 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 other best practices. Attendees will walk away with enough knowledge to publish their own quality PHP packages on Packagist for others to use.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Releasing High-Quality Packages - php[world] 2018

  1. 1. @colinodell Releasing High-Quality Packages @colinodell
  2. 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 at Unleashed Technologies
  3. 3. @colinodell What Are Packages? Reusable libraries; installed via Composer
  4. 4. @colinodell PEAR / PHPClasses.org
  5. 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: 197,000 Packages on Packagist 1.4 million Unique Releases
  6. 6. @colinodell Package Benefits • Pre-written • Reusable • Community-maintained • Framework-agnostic • Easily installed • Robust dependency resolution
  7. 7. @colinodell Releasing Your Own Packages
  8. 8. @colinodell Overview Definition of Quality Project Structure Testing Packaging Releasing Ongoing Maintenance Development Best Practices
  9. 9. @colinodell
  10. 10. @colinodell Project Structure
  11. 11. @colinodell Project Structure
  12. 12. @colinodell Project & Vendor Name There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
  13. 13. @colinodell Project & Vendor Name PHP namespace = VendorNameProjectName Packagist repo = vendor-name/project-name • Two parts: • Vendor = person, group, company, or organization • Project = individual package • Choosing a vendor name: • Available • Unique • Easy to search • Make names consistent
  14. 14. @colinodell
  15. 15. @colinodell composer.json • Meta info • Project dependencies • Include PHP version & extensions • Development dependencies • Autoloading configuration • PSR-4 not PSR-0 • Separate namespace for tests
  16. 16. @colinodell Source Code
  17. 17. @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?)
  18. 18. @colinodell Project Hosting Features: • Project downloads • Issue reporting • Pull requests / code reviews • Collaboration • CI integrations
  19. 19. @colinodell Testing Automating the testing process
  20. 20. @colinodell Automated Tests
  21. 21. @colinodell Unit Tests • Test individual components • PHPUnit – defacto standard • Aim for 80% code coverage
  22. 22. @colinodell
  23. 23. @colinodell Automated Tests • Not just unit tests: • Functional tests • Integration tests • Acceptance tests • Other good test frameworks: • Phpspec • Behat • Codeception • Use continuous integration!
  24. 24. @colinodell Continuous Integration
  25. 25. @colinodell Continuous Integration
  26. 26. @colinodell Continuous Integration • Run tests… • Across all supported PHP versions • Against future PHP versions • Using minimal/older Composer constraints • Track code quality • Scrutinizer CI • Check code style • StyleCI • PHPCS
  27. 27. @colinodell .travis.yml
  28. 28. @colinodell .styleci.yml
  29. 29. @colinodell
  30. 30. @colinodell Project Structure
  31. 31. @colinodell Packaging Getting the code ready for distribution
  32. 32. @colinodell Licensing • Distribution • Attribution •Modifications •Commercial Use Permissive: MIT; BSD; ISC Prevent Closed Source: GPLv3; Mozilla Public License Documentation: Creative Commons
  33. 33. @colinodell Licensing • choosealicense.com • creativecommons.org/choose
  34. 34. @colinodell Licensing
  35. 35. @colinodell Licensing
  36. 36. @colinodell Project Structure
  37. 37. @colinodell Documentation: README.md • Badges • What problem your package solves • Installation steps • Sample Usage • Configuration
  38. 38. @colinodell Documentation: docblocks Benefits: • Read docs while coding • IDE auto-completion • Short description • Parameter types, names, and purposes • Return types • Any thrown exceptions
  39. 39. @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
  40. 40. @colinodell Archive Settings Package consumers (probably) don’t want: • Tests • Dev dependencies • Issue / PR templates • Travis CI configuration • Your .gitignore development settings
  41. 41. @colinodell Archive Settings - .gitattributes
  42. 42. @colinodell Archive Settings: composer.json { {
  43. 43. @colinodell Project Structure
  44. 44. @colinodell Packagist.org
  45. 45. @colinodell Releasing Launching your package
  46. 46. @colinodell Semantic Versioning – semver.org x . y . zMajor . Minor . Patch
  47. 47. @colinodell Semantic Versioning – semver.org 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  48. 48. @colinodell 2 . 4 . 6 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  49. 49. @colinodell 2 . 5 . 0 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  50. 50. @colinodell 3 . 0 . 0 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  51. 51. @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
  52. 52. @colinodell CHANGELOG.md • Follow https://keepachangelog.com
  53. 53. @colinodell
  54. 54. @colinodell UPGRADE.md • Documentation on upgrading between major versions • Describe BC breaks • Provide instructions for users to update their code
  55. 55. @colinodell
  56. 56. @colinodell Tagging a Release
  57. 57. @colinodell Released!
  58. 58. @colinodell Project Structure
  59. 59. @colinodell Ongoing Maintenance Addressing issues, handling PRs, and maintaining your community
  60. 60. @colinodell Maintainer Responsibilities • Be responsive • Triage issues; keep queue clean • Review PRs & provide feedback • Share responsibility with core contributors
  61. 61. @colinodell CONTRIBUTING.md • Requirements • Considerations • Process • Tips
  62. 62. @colinodell Issue / PR Templates
  63. 63. @colinodell Issue / PR Templates
  64. 64. @colinodell Issue / PR Templates
  65. 65. @colinodell Issue / PR Templates
  66. 66. @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/
  67. 67. @colinodell .editorconfig • Defines preferred indentation style and line breaks • Automatically configures contributor IDEs • Most major IDEs supported
  68. 68. @colinodell .gitignore Ensures certain files are never committed to Git
  69. 69. @colinodell Project Structure
  70. 70. @colinodell Further Reading Additional information and resources on creating high-quality PHP packages
  71. 71. @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
  72. 72. @colinodell Questions?
  73. 73. @colinodell Feedback Appreciated! https://joind.in/talk/42353 @colinodell Thanks!

×