Best Practices for Releasing and Choosing Open Source Projects

The Open Source community is one of vast reach. Releasing software as open source is now the norm. Simultaneously, the value of using Open Source software in one's codebase is increasingly evident. Given that, how does one release a project or choose the right project to use? In this talk, we'll cover best practices for releasing projects as open source, and how those will impact consumers of open source software.

Transcript

1. 2015
   Best Practices for Releasing
   and Choosing Open Source
   Software
   Irene Ros
   Oct 15th, 2015
   #GHC15
   2015
   

   View Slide

2. 2015
   Who am I?
   ▪ Working on the Open Web (~ 9 years)
   ▪ Large and small companies
   ▪ Consumer and Producer of Open Source
   Software
   Data Visualization team
   

   View Slide

3. 2015
   Why should you care about Open
   Source code?
   No software is built without it.
   Period.
   

   View Slide

4. 2015
   If you're a consumer...
   ▪ Your open source software should:
   ▪ Do the job
   ▪ Do it well
   ▪ Be easy to work with
   ▪ Be easy to adapt to your needs
   ▪ Not break easily
   ▪ Be maintained and supported
   ▪ Have other users
   ▪ Follow accepted paradigms/specifications
   

   View Slide

5. 2015
   If you're a producer...
   ▪ You want your open source software to:
   ▪ Be useful to people
   ▪ Be used by a lot of people
   ▪ Be fun to work on
   ▪ Be fun to maintain/support/grow
   

   View Slide

6. 2015
   Dear Open Source Creators...
   

   View Slide

7. 2015
   Code Repositories
   

   View Slide

8. 2015
   Choosing a code repository
   ▪ Many options: Github, Bitbucket, CodePlex 

   (MS), etc
   ▪ Things to consider:
   ▪ Git vs Not Git (svn, cvs... don't.)
   ▪ Pricing (Team vs Individual)
   ▪ Private vs Public
   ▪ Discoverability for potential consumers
   

   View Slide

9. 2015
   Choosing a code repository
   ▪ More things to consider:
   ▪ Ease of adding collaborators
   ▪ Ease of "following along"
   ▪ Ease of submitting support requests
   ▪ Ease of interfacing with other engineering 

   tools (build systems, test systems, 

   publishing etc.)
   ▪ Ease of communicating about your open source
   project (documentation, wiki etc.)
   

   View Slide

10. 2015
    Documentation
    

    View Slide

11. 2015
    Documenting Your Project
    ▪ Code is only 10% of the work.
    ▪ Documentation should always have:
    ▪ Installation instructions
    ▪ Usage instructions/tutorials/examples
    ▪ Instructions on modifying/extending
    ▪ Dependencies
    ▪ Caveats
    ▪ Maintainers and how to contact them
    ▪ Instructions on support requests
    ▪ Guidelines for interested contributors
    ▪ Credits to other contributors / software
    ▪ Make it
    Searchable
    ▪ Keep it up to
    date
    ▪ Allow people to
    fix it if you can't
    ▪ Keep it as simple
    as possible
    ▪ Document edge
    cases
    

    View Slide

12. View Slide

13. 2015
    Versioning
    

    View Slide

14. 2015
    Version it!
    ▪ Things break - that's why we version things:
    ▪ http://semver.org/
    ▪ For example (if we look at 2.5.6):
    ▪ (2) Major for breaking API changes
    ▪ (5) Minor for adding backwards compatible new functionality
    ▪ (6) Patch for backward-compatible bug fixes
    ▪ Document on which platforms each version works, so that
    people who are locked into certain platforms can find older
    versions.
    ▪ Make older versions available (publish or download.)
    ▪ Publish a Change Log / Release Notes
    

    View Slide

15. View Slide

16. 2015
    Licenses
    

    View Slide

17. 2015
    Licenses
    

    View Slide

18. 2015
    Licenses
    ▪ choosealicense.com
    ▪ Permissive licenses (BSD) mean:
    ▪ more people can use your software (especially
    large companies.)
    ▪ people can commercialize your software/code
    ▪ people can copy your code with attribution
    ▪ you are not held liable
    

    View Slide

19. 2015
    Licenses
    ▪ "Sticky" Copyleft Licenses (GPL*) means:
    ▪ Anyone who redistributes your code MUST use
    the same license
    ▪ Larger companies will avoid it like fire (because
    they have products they want to sell and not
    release as open source.)
    ▪ Some restrict modification
    

    View Slide

20. 2015
    Licenses
    ▪ Other:
    ▪ Apache License - similar to MIT in
    permissiveness, but reserves right to patent.
    ▪ MPL - between MIT and GPL
    ▪ Creative Commons - mostly content, not code
    ▪ more: http://choosealicense.com/licenses/
    ▪ Don't make up your own
    ▪ You should absolutely have one
    

    View Slide

21. 2015
    Support
    

    View Slide

22. 2015
    Offer Support
    ▪ Make sure you choose a platform that:
    ▪ Users can submit support requests / issues on
    ▪ Users can get an update on their issues
    ▪ Inform users what information you need
    (Environment, screenshots, reproducible steps etc)
    ▪ Update tickets - always respond with
    acknowledgement, plan and resolution
    

    View Slide

23. 2015
    Community
    

    View Slide

24. 2015
    Community is Key
    ▪ Your code is worthless without its users.
    ▪ You should always:
    ▪ Answer questions (StackOverflow, google groups,
    IRC etc.)
    ▪ Update on the status of your work and planned
    changes/improvements
    ▪ Appreciate and engage contributors
    ▪ Be honest about your investment
    ▪ Be nice to your community and your competitors
    

    View Slide

25. 2015
    It's not all sunshine and roses...
    
    The less pleasant side of Open Source Publishing
    

    View Slide

26. 2015
    ▪ Needing to fix bugs that arise due to platform
    changes, not your own code.
    ▪ Ridiculous / angry user requests
    ▪ People "copying" your code and calling it their
    own
    ▪ The consequences of success (stability vs
    growth, "competition", commercial application,
    support demand)
    ▪ No one caring
    

    View Slide

27. 2015
    Open Source is a long term
    commitment.
    

    View Slide

28. 2015
    Dear Users of Open Source...
    

    View Slide

29. 2015
    Things to look out for...
    ▪ Is the project active? 

    (commits, releases, issues, dev priorities etc.)
    ▪ is it good code? 

    (good organization, good practices)
    ▪ Is it easy to adapt?

    (are there extensions/plugins?)
    ▪ Is it well supported? 

    (Issues - How many are open and
    unanswered? How severe are they?)
    

    View Slide

30. 2015
    Things to look out for...
    ▪ Is it well documented? 

    (Does it exist and is it good?)
    ▪ Can YOU use this project?

    (Compatible license?)
    ▪ Does it have a community?

    (Is anyone using it? Are there conversations
    about it? are there community helpers?)
    

    View Slide

31. 2015
    Sometimes things go wrong...
    ▪ Maintainers become disinterested OR the
    need is eliminated
    ▪ There's no community involvement /
    contribution
    ▪ Code libraries "break" as platforms evolve
    (aka, no longer compatible)
    ▪ Open source libraries are written in a way
    that makes them hard to extend/fix
    

    View Slide

32. 2015
    Be diligent in your choices.
    
    Be nice.
    

    View Slide

33. 2015
    Got Feedback?
    Rate and review the session on our mobile app
    Download at http://ddut.ch/ghc15
    or search GHC 2015 in the app store
    Thank you!
    irene@bocoup.com
    @ireneros
    

    View Slide