Maintaining Open Source While Maintaining Your Sanity

Simon MacDonald


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


  • 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!!!


Submitter is asking for new functionality


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
    • 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


  • Gotta Have Them
  • Not a Lot
  • Mostly for Regression


  • Bare minimum start with a README
  • Enhance with markdown docs that are linked from the README
  • Graduate to docs for GitHub pages


  • Release on every commit
  • Release on a time based schedule

Automate Your Release



Further Reading

Maintaining Open Source While Maintaining Your Sanity

By Simon MacDonald

Maintaining Open Source While Maintaining Your Sanity

AEM GEMS Session

  • 857
Loading comments...

More from Simon MacDonald