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.

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
Director of Technology
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: 213,660
Packages on Packagist
1.6 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
Definition of Quality
Semantically
Versioned
Actively
Maintained
User Friendly Composer
Installable
Extensively
Documented
S A U C E

11. @colinodell
Project Structure

12. @colinodell
Project
Structure

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

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

16. @colinodell
composer.json
• Project dependencies
• Include PHP version &
extensions
• Development dependencies
• Autoloading configuration
• PSR-4 not PSR-0
• Separate namespace
for tests

17. @colinodell
Source
Code

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

20. @colinodell
Testing
Automating the testing process

21. @colinodell
Automated
Tests

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

23. @colinodell

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

26. @colinodell
Continuous Integration

27. @colinodell
Continuous Integration
• Run tests across all supported
versions
• Track code quality
• Scrutinizer CI
• Check code style
• StyleCI
• PHPCS

28. @colinodell
.travis.yml

29. @colinodell
.styleci.yml

30. @colinodell

31. @colinodell
Project
Structure

32. @colinodell
Packaging
Getting the code ready for distribution

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

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

35. @colinodell
Licensing

36. @colinodell
Licensing

37. @colinodell
Project
Structure

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

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

42. @colinodell
Archive Settings - .gitattributes

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

44. @colinodell
Project
Structure

45. @colinodell
Packagist.org

46. @colinodell
Releasing
Launching your package

47. @colinodell
Semantic Versioning – semver.org
1.0.0 (stable)
or
0.1.0 (unstable)

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

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

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

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

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

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

55. @colinodell

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

57. @colinodell

58. @colinodell
Tagging a
Release

59. @colinodell
Released!

60. @colinodell
Project
Structure

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

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

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

64. @colinodell
Issue / PR Templates

65. @colinodell
Issue / PR Templates

66. @colinodell
Issue / PR Templates

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

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

70. @colinodell
Project
Structure

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

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

74. @colinodell
@colinodell
Thanks!