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.

1. @colinodell
Releasing High-Quality
Packages
@colinodell

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. @colinodell
What Are Packages?
Reusable libraries;
installed via Composer

4. @colinodell
PEAR / PHPClasses.org

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. @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
Project Structure

11. @colinodell
Project
Structure

12. @colinodell
Project & Vendor Name
There are only two hard things in Computer
Science: cache invalidation and naming things.
-- Phil Karlton

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. @colinodell

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. @colinodell
Source
Code

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. @colinodell
Project Hosting
Features:
• Project downloads
• Issue reporting
• Pull requests / code reviews
• Collaboration
• CI integrations

19. @colinodell
Testing
Automating the testing process

20. @colinodell
Automated
Tests

21. @colinodell
Unit Tests
• Test individual
components
• PHPUnit – defacto
standard
• Aim for 80% code
coverage

22. @colinodell

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. @colinodell
Continuous Integration

25. @colinodell
Continuous Integration

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. @colinodell
.travis.yml

28. @colinodell
.styleci.yml

29. @colinodell

30. @colinodell
Project
Structure

31. @colinodell
Packaging
Getting the code ready for distribution

32. @colinodell
Licensing
• Distribution
• Attribution
•Modifications
•Commercial Use
Permissive: MIT; BSD; ISC
Prevent Closed Source: GPLv3; Mozilla Public License
Documentation: Creative Commons

33. @colinodell
Licensing
• choosealicense.com
• creativecommons.org/choose

34. @colinodell
Licensing

35. @colinodell
Licensing

36. @colinodell
Project
Structure

37. @colinodell
Documentation:
README.md
• Badges
• What problem your package solves
• Installation steps
• Sample Usage
• Configuration

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. @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. @colinodell
Archive Settings
Package consumers (probably) don’t want:
• Tests
• Dev dependencies
• Issue / PR templates
• Travis CI configuration
• Your .gitignore development settings

41. @colinodell
Archive Settings - .gitattributes

42. @colinodell
Archive Settings:
composer.json
{
{

43. @colinodell
Project
Structure

44. @colinodell
Packagist.org

45. @colinodell
Releasing
Launching your package

46. @colinodell
Semantic Versioning – semver.org
x . y . zMajor . Minor . Patch

47. @colinodell
Semantic Versioning – semver.org
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

48. @colinodell
2 . 4 . 6
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

49. @colinodell
2 . 5 . 0
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

50. @colinodell
3 . 0 . 0
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

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. @colinodell
CHANGELOG.md
• Follow https://keepachangelog.com

53. @colinodell

54. @colinodell
UPGRADE.md
• Documentation on upgrading between major versions
• Describe BC breaks
• Provide instructions for users to update their code

55. @colinodell

56. @colinodell
Tagging a
Release

57. @colinodell
Released!

58. @colinodell
Project
Structure

59. @colinodell
Ongoing Maintenance
Addressing issues, handling PRs, and maintaining your community

60. @colinodell
Maintainer Responsibilities
• Be responsive
• Triage issues; keep queue clean
• Review PRs & provide feedback
• Share responsibility with core contributors

61. @colinodell
CONTRIBUTING.md
• Requirements
• Considerations
• Process
• Tips

62. @colinodell
Issue / PR Templates

63. @colinodell
Issue / PR Templates

64. @colinodell
Issue / PR Templates

65. @colinodell
Issue / PR Templates

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. @colinodell
.editorconfig
• Defines preferred indentation style and line breaks
• Automatically configures contributor IDEs
• Most major IDEs supported

68. @colinodell
.gitignore
Ensures certain files are never committed to Git

69. @colinodell
Project
Structure

70. @colinodell
Further Reading
Additional information and resources on creating high-quality PHP packages

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. @colinodell
Questions?

73. @colinodell
Feedback Appreciated!
https://joind.in/talk/42353
@colinodell
Thanks!