Fork me on GitHub

Good practices for Open Source projects

In this article, I gathered some good practices for open source projects.

I made my best to keep it short and not too verbose. If you want to discuss, contribute or enhance this article, simply use Github !

Documentation

  • A README file is the bare minimum
  • More documentation content is to be stored in a docs/ folder
  • Use the fabulous Read the Docs service
  • Mention the license and copyright holder
  • Explain why this project was created
  • Mention existing related projects
  • How to install and use it ?
  • Frequently asked questions (time saver)
  • Link to the list of contributors
  • Provide details about design and architecture
  • Give instructions to developers on how to contribute
  • Mention what you expect from contributors (Definition-of-Done, checklist, conventions...)

Source code

  • Use English everywhere
  • Use a decentralized versioning system (Git, mercurial, ...)
  • Unit test your code. Software without tests is broken by design
  • Setup continuous integration (with TravisCI)
  • Follow the programming language conventions (PEP8, JSLint, ...)
  • Follow the framework conventions, and list explicitly the infringements you decided to make in the documentation
  • Be a professional coder, by following Uncle Bob recommendations
  • Use a translation system, like gettext, and keep English as the default language
  • Enable collaborative translation of your app with Transifex
  • Provide simple commands to install or run tests (in a Makefile for example)
  • Test your project features (functional tests)
  • Make sure the tests self-describe your project specifications

Releases

  • Use semantic versionning (main version, features change, bug fixes)
  • Keep a list of changes by version (Changelog)
  • Follow some workflow for your changelog (Include it in docs, update it in the merge commit of pull-requests, read more recommendations...)
  • Create a tag for each release (vX.Y.Z)
  • Create a branch for each version (recommended workflow)
  • Publish your release (backup copy) in a repository (PyPi, NPM)
  • Automate your release process (Makefile, Zest releaser, npm)
  • Release often, release early
  • Communicate about new versions (tweet, OpenHub, Freecode, ...)

Community

  • Make sure users can interact somewhere about your project (UserVoice, Google groups, ...)
  • Setup alerts on Stackoverflow to help users and promote your project
  • Make your best to find at least one valuable contributor, and give him permissions on the repository
  • Be clear about the project functional perimeter
  • Reject every addition of feature that introduces complexity or twists the project main use cases
  • Look for a successor as soon as the motivation goes down

History

  • History of commits is as valuable as comments in the source code
  • Mention the ticket number in the commit messages (e.g. Update specs (ref #123))
  • Respect the commits messages formatting of your community (e.g. Drupal's prefixes like CHG, DOC...)

Workflow

  • Keep the master branch stable
  • Create a dedicated branch with an explicit name for each feature (e.g. 187_add_drop_down_menu)
  • Use pull-requests
  • Even if you are the owner, and alone in your project, use pull-requests (allows code review, triggers integration tests, history is clearer, ...)
  • Ideally, who merges the pull-request is not its author
  • Ideally merge branches with the no fast-forward option (git merge --no-ff)
  • Create a develop branch in case of major refactoring, or follow a proper Git workflow to ease merging

Github

  • Use Github
  • Use Github issues (as much as you can, for everything)
  • Even if you are alone, use Github issues as a TODO list
  • Create some standard labels (help-needed, docs, duplicate ...)
  • Use the fantastic checklists feature in issues and pull-requests descriptions
  • Take advantage of the milestones, for the next version, or for a general roadmap (e.g. Soon, Later, Final 1.0, ...)
  • Categorize the labels, renaming them with a convention (e.g. priority: low, priority: high, ...)
  • Copy the changelog parts into the dedicated releases page
  • Use the contributing feature
  • Use the gh-pages feature to demo your project
  • Configure the main branch in the settings

Comments !

social