Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

Releasing High Quality PHP Packages - ConFoo Montreal 2019

192 vues

Publié le

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.

Publié dans : Logiciels
  • Soyez le premier à commenter

  • Soyez le premier à aimer ceci

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!

×