Maintaining Open Source While Maintaining Your Sanity
Simon MacDonald
simonmacdonald.com
@macdonst
May You Maintain A Popular Open Source Project
- Developer Curse
Setting Up Your Project
Include a README
- Overview
- Getting Started Instructions
- An Invitation to Contribute
Have a CONTRIBUTING doc
- How to send a Pull Request
- Style Guide
Code of Conduct
- Helps create a positive social atmosphere for your community
- Should include:
- Where it takes effect
- Whom does it apply to
- What happens when someone violates the code
- How does one report violations
- The earlier you establish one the better
Add a License
Any License
Well, Almost Any License
Decide on How to Handle
Issues vs Question
- Everything in GitHub Issues
-
OR
Bugs only in GitHub Issues,
Questions on StackOverflow
Speaking of Issues
Create an Issue Template
What Goes in a Good Issue Template?
- Ask if the user has searched past issue
- Expected Behaviour
- Actual Behaviour
- Reproduction Scenario
- Version
- Sample Code
- Logs
Triaging Issues
Submitter doesn't follow issue template!
Submitter asks a question that has been answered before!!
Requested an Update 2 Months Ago and No Reply
Submitter Asks a Dumb/Obvious Question!!!
docs
Submitter is asking for new functionality
enhancement
Issue template filled
and it's reproducible!
Mark as a bug
People are more difficult than code
Set Boundaries
Be respectful, empathic but firm
What About Pull Requests?
You Should Have a Pull Request Template
- Description
- Related Issue
- Type of Change:
- Bug fix
- New feature
- Breaking Change
- Checklist
- Follows code style
- Doc change
- Read CONTRIBUTING
- Added tests
- All tests pass
You Don't Have To Merge in Every Pull Request
Open Source
Starter Repo
Building Community
Make it easy for people to contribute
- Identify beginner bugs
- Document the heck out of things
- Give people other ways to contribute besides writing code.
Turn contributors into maintainers
Thank People For Their Efforts
Tests
- Gotta Have Them
- Not a Lot
- Mostly for Regression
Documentation
- Bare minimum start with a README
- Enhance with markdown docs that are linked from the README
- Graduate to docs for GitHub pages
Releasing
- Release on every commit
- Release on a time based schedule
Automate Your Release
Remember
Resources
Further Reading
Maintaining Open Source While Maintaining Your Sanity
By Simon MacDonald
Maintaining Open Source While Maintaining Your Sanity
AEM GEMS Session
- 2,460