Good practices for Open Source projects

Tue 19 August 2014

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...)

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

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, ...)

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 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...)

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

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

#opensource, #github, #git - Posted in the Dev category

Content licensed under the Creative Commons attribution-noncommercial-sharealike License.