THE EQUIPMENT OF CONTRIBUTIONChris Johnson

Phase2 Technologycjohnson@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

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.

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 assetsIssue reporting and tracking - identification and prioritization of errors, roadmap developmentDocumentation and support - helps users help themselves, reduces communication burden on project maintainersDelegation - other tools need to support this so that others can be given more contribution capabilities to distribute workload

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.

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.

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.

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,

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 evolutionIssue reporting and tracking - bug tracking systemDocumentation - wiki, forums, mailing listsDelegation - ways to let trusted users join and take on some of the workload of a projectEvangelism - not necessarily a tool of your hosting but all projects need some sort of promotion so that people know they exist