1. THE EQUIPMENT OF CONTRIBUTION
Chris Johnson
Phase2 Technology
cjohnson@phase2technology.com
There are many ways to release your code, from ancient (in internet
terms) methods like posting a bundle to a news group or a mailing list
to more modern methods involving hosting code repositories, issue
trackers, wikis, mailing lists, etc. The central thing to remember when
deciding what tools and infrastructure you need when releasing an
open source project is
2. CONTRIBUTION IS COMMUNICATION
• Pick tools that support the type of communication you
want to have
New Project Existing Project
Publication
Conversation
Contribution is communication. The types of tools that you need and
the success of your project relate directly to the type of communication
you want to have with your users.
The tools you’ll use vary between new and existing projects. And the
tools for publication are much simpler than those that allow for a
conversation with others about your code.
But one of the essential aspects of open source is that a large part of
the value comes from the conversation and communication.
3. ESSENTIAL COMMUNICATION TOOLS
• Version control
• Issue Reporting and Tracking
• Documentation and Support
• Delegation
All projects have some essential tools to help facilitate conversation at different levels
(and note that developer and user can have quite a lot of overlap)
Version control - who said what at the code level - how developers talk to each other
but don’t overlook version control for documentation and non code based assets
Issue reporting and tracking - identification and prioritization of errors, roadmap
development
Documentation and support - helps users help themselves, reduces communication
burden on project maintainers
Delegation - other tools need to support this so that others can be given more
contribution capabilities to distribute workload
4. EXISTING PROJECT
• Problem Solved
• Get access to existing infrastructure
• Three Examples
• Linux, Drupal, Jenkins
• Be Aware of Licensing
Let’s talk about the easy stuff first. An existing project will likely already have code repositories, issue tracking and documentation infrastructure in place and it’s just a matter of learning how the
project works and asking the right person for the access you need. By the time you have contributions for an existing project you probably already know much of this.
As an example, the three projects listed have fairly different contribution mechanisms. For the linux kernel this is generally done through sets of discussions on a mailing list along with attached
patches. Trusted maintainers patch their repositories and then these flow to the main repository from which new distributions are released.
For Drupal, anyone can create an account on Drupal.org which lets them create a sandbox project, participate in issue queues (where patches are posted) and edit documentation. After going through
an approval process you can make sandboxed code an official contributed project.
Jenkins, which is a project that creates a continuous integration server, access to the code on GitHub is requested on the mailing list. Generally to transfer an existing GitHub repo containing your
contributions to the main Jenkins account. Access to the wiki and Jira is done via self service account creation.
Be aware that sometimes using a project’s infrastructure means using their licensing. If that is not acceptable, then your contributions should be considered a new project.
5. NEW PROJECT
• Conversation or Publication
• Be clear with users which you are doing
When you are starting one from scratch you need to decide whether you are trying to start a
conversation or just publish some code.
Publication is the most simple, you might not even need any new infrastructure as you can
place a download on your existing web site or post it to a mailing list.
It is also important to be clear about what you are doing, especially in the publication model.
The default stance with open source is that by making your code publicly available there is
some minimum level of involvement you would like to have with those trying to use your
code or contribute back to it. If you just want someone to take it as a starting point then you
should be very clear about that.
6. PUBLICATION
• Use systems that allow projects to evolve
• Distributed version control
• Some hosting options
• SourceForge
• Google Code
• GitHub
• BitBucket
Even if you want to use a publication model, I would encourage you to do it in a
way that a conversation can grow without your involvement. You can do this by
using tools where people can easily copy and extend what you have produced.
I’ve listed some hosting options that are particularly suited to open source,
there are a plethora of others. Some of these are particularly well suited to
turning a publication model into a conversation model (GitHub for example
allows easy forking of repositories so someone could take your code, extend it
and start a community around it if they had the desire). While this is possible
with any publication model, it’s easier on some systems than others.
7. MAKE IT EASY TO START
• Documentation, Documentation, Documentation
• Answer the right questions for new people
• What does this do?
• How do I get it?
• How do I use it?
• How do I improve this and contribute back?
• Publicize availability
• Blog Posts, Press Releases, Twitter, Conferences,
Journals Articles, Civic Commons
Regardless of what type of communication you want it’s critical to make it easy to start. Which usually involves
mainly documentation: examples, with screenshots, screencasts, tutorials, walk throughs, etc. The lower the
barrier between someone seeing your project, figuring out that it would be useful for them and downloading it
and having it running the better. And as soon as they’ve done that, you want to be sure they know how to
contribute back when they make improvements.
Especially for new projects don’t neglect letting the world know it’s out there. Go where people who would find
your project useful hang out and tell them about it.
Code for america has sponsored a project called Civic Commons especially for documenting and publicizing
projects that might be of interest to government. For those that might be in the DoD there’s Forge.mil,
8. NEW PROJECT TOOLS
• Version control
• Issue Reporting and Tracking
• Documentation
• Delegation
• Evangelism
When you are evaluating where to host your project, consider that you
are going to need at minimum some of the following capabilities:
Version control - to track code evolution
Issue reporting and tracking - bug tracking system
Documentation - wiki, forums, mailing lists
Delegation - ways to let trusted users join and take on some of the
workload of a project
Evangelism - not necessarily a tool of your hosting but all projects need
some sort of promotion so that people know they exist