Successfully reported this slideshow.
Your SlideShare is downloading. ×

Releasing High Quality PHP Packages - ConFoo Montreal 2019

Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Loading in …3
×

Check these out next

1 of 74 Ad

Releasing High Quality PHP Packages - ConFoo Montreal 2019

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.

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.

Advertisement
Advertisement

More Related Content

Slideshows for you (20)

Similar to Releasing High Quality PHP Packages - ConFoo Montreal 2019 (20)

Advertisement

More from Colin O'Dell (20)

Recently uploaded (20)

Advertisement

Releasing High Quality PHP Packages - ConFoo Montreal 2019

  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 Director of Technology 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: 213,660 Packages on Packagist 1.6 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 Definition of Quality Semantically Versioned Actively Maintained User Friendly Composer Installable Extensively Documented S A U C E
  11. 11. @colinodell Project Structure
  12. 12. @colinodell Project Structure
  13. 13. @colinodell Project & Vendor Name There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
  14. 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. 15. @colinodell
  16. 16. @colinodell composer.json • Project dependencies • Include PHP version & extensions • Development dependencies • Autoloading configuration • PSR-4 not PSR-0 • Separate namespace for tests
  17. 17. @colinodell Source Code
  18. 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. 19. @colinodell Project Hosting Features: • Project downloads • Issue reporting • Pull requests / code reviews • Collaboration • CI integrations
  20. 20. @colinodell Testing Automating the testing process
  21. 21. @colinodell Automated Tests
  22. 22. @colinodell Unit Tests • Test individual components • PHPUnit – defacto standard • Aim for 80% code coverage
  23. 23. @colinodell
  24. 24. @colinodell Automated Tests • Not just unit tests: • Functional tests • Integration tests • Acceptance tests • Other good test frameworks: • Phpspec • Behat • Codeception • Use continuous integration!
  25. 25. @colinodell Continuous Integration
  26. 26. @colinodell Continuous Integration
  27. 27. @colinodell Continuous Integration • Run tests across all supported versions • Track code quality • Scrutinizer CI • Check code style • StyleCI • PHPCS
  28. 28. @colinodell .travis.yml
  29. 29. @colinodell .styleci.yml
  30. 30. @colinodell
  31. 31. @colinodell Project Structure
  32. 32. @colinodell Packaging Getting the code ready for distribution
  33. 33. @colinodell Licensing • Distribution • Attribution •Modifications •Commercial Use Permissive: MIT; BSD; ISC Prevent Closed Source: GPLv3; Mozilla Public License Documentation: Creative Commons
  34. 34. @colinodell Licensing • choosealicense.com • creativecommons.org/choose
  35. 35. @colinodell Licensing
  36. 36. @colinodell Licensing
  37. 37. @colinodell Project Structure
  38. 38. @colinodell Documentation: README.md • Badges • What problem your package solves • Installation steps • Sample Usage • Configuration
  39. 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. 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. 41. @colinodell Archive Settings Package consumers (probably) don’t want: • Tests • Dev dependencies • Issue / PR templates • Travis CI configuration • Your .gitignore development settings
  42. 42. @colinodell Archive Settings - .gitattributes
  43. 43. @colinodell Archive Settings: composer.json { {
  44. 44. @colinodell Project Structure
  45. 45. @colinodell Packagist.org
  46. 46. @colinodell Releasing Launching your package
  47. 47. @colinodell Semantic Versioning – semver.org 1.0.0 (stable) or 0.1.0 (unstable)
  48. 48. @colinodell Semantic Versioning – semver.org x . y . zMajor . Minor . Patch
  49. 49. @colinodell Semantic Versioning – semver.org 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  50. 50. @colinodell 2 . 4 . 6 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  51. 51. @colinodell 2 . 5 . 0 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  52. 52. @colinodell 3 . 0 . 0 2 . 4 . 5Major . Minor . Patch Incompatible Changes Backwards- Compatible; New Features Bug Fixes
  53. 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
  54. 54. @colinodell CHANGELOG.md • Follow https://keepachangelog.com
  55. 55. @colinodell
  56. 56. @colinodell UPGRADE.md • Documentation on upgrading between major versions • Describe BC breaks • Provide instructions for users to update their code
  57. 57. @colinodell
  58. 58. @colinodell Tagging a Release
  59. 59. @colinodell Released!
  60. 60. @colinodell Project Structure
  61. 61. @colinodell Ongoing Maintenance Addressing issues, handling PRs, and maintaining your community
  62. 62. @colinodell Maintainer Responsibilities • Be responsive • Triage issues; keep queue clean • Review PRs & provide feedback • Share responsibility with core contributors
  63. 63. @colinodell CONTRIBUTING.md • Requirements • Considerations • Process • Tips
  64. 64. @colinodell Issue / PR Templates
  65. 65. @colinodell Issue / PR Templates
  66. 66. @colinodell Issue / PR Templates
  67. 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. 68. @colinodell .editorconfig • Defines preferred indentation style and line breaks • Automatically configures contributor IDEs • Most major IDEs supported
  69. 69. @colinodell .gitignore Ensures certain files are never committed to Git
  70. 70. @colinodell Project Structure
  71. 71. @colinodell Further Reading Additional information and resources on creating high-quality PHP packages
  72. 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
  73. 73. @colinodell Questions?
  74. 74. @colinodell @colinodell Thanks!

Editor's Notes

  • 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
  • ---
    Community-created bundle of code
    Provides useful functionality


    It wasn’t always this easy
  • Virtually no interoperability

  • Framework Interoperability Group
    Autoloading eliminated need to manually require_once
  • 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?
  • More than just throwing code online
  • Packages and what makes them high-quality

    Look at structure of a quality package

    And the steps to prepare, release, and maintain your package
  • Everyone has their own definition

    Great staring point but not exhaustive
  • Look at quality through the lens of good project structure
  • This will serve as our checklist
  • Two parts:
    Vendor = person, group, company, or organization
    Project = individual package
  • (click once)
    1. Meta info (click again)

  • Logging: PSR-3
    HTTP: PSR-7, 13, 15, 17
    Caching: PSR-6, 16
    Containers: PSR-11
  • “test bench”
  • Automatically runs tasks when:
    Code is pushed
    PR is created
    Code is merged
    New version is released
    Perfect for tests!
  • Run tests:
    Across all supported PHP versions
    Against future PHP versions
    Using minimal/older Composer constraints
  • Copyright
    Mention license
  • First impression

  • At this point,
    Package is registered but not “released” – no versions available
  • Safe upgrading
  • Safe upgrading
  • Safe upgrading
  • Safe upgrading
  • Great for new libraries where architecture isn’t finalized
  • Added
    Changed
    Fixed
    Deprecated
    Removed

×