Moving between the stages of open source projects

No readers like this yet.
A diagram of a bug.

Opensource.com

In a recent training session, I discussed commitment gradients—how much extra effort is involved to move between each stage of involvement within a project.  After the session I was asked for some examples of commitment gradients and how it’s possible to make them shallower, so it’s easier for people to progress their involvement in a project.

A desireable project

This graph represents a desirable commitment gradient.  The move from knowing about the project to using and discussing it is fairly trivial.  Reporting bugs requires some extra knowledge, e.g. using the bug tracker, but isn’t a significantly harder step.  Contributing patches is slightly harder as it requires knowledge of the programming language and awareness of things such as coding styles.  Finally, moving into a leadership role requires significant additional effort, as leaders need to have an awareness of all aspects of the project, including understanding of the governance model, as well as having gained the confidence of other community members.

Using the software

A hard installation

This graph represents a project where the software is so hard to install that you need to have intimate knowledge of the project to even get it working.  For example, if configuration settings are hard-coded, setting the software up involves knowledge of the language, changing the code, then compiling it yourself before you even get started.  By this point, you know the software so well that there’s nearly no extra effort required for the following stages, but most people won’t bother, and your user base will suffer.

To make the commitment gradient lower at this stage, a project should make it easy to acquire, install and configure its outputs.  For example, having packaged versions in the software repositories or app stores for the target platforms makes installation easier.  Where this isn’t appropriate, an automated installer requiring little technical knowledge (such as that used by WordPress) can be used as an option for beginners, with a more configurable “expert’s mode” available for more experienced users.  For configuration, being able to change settings through the software’s interface rather than in code or configuration files is helpful.

Discussing the project

A hostile community

This graph represents a project where the software is easy to use, but the community has an elitist attitude and is hostile to newcomers.  Responses to questions asked assume deep technical understanding of the software, and people who don’t have such understanding are expected to find out for themselves before they engage with those who do.

The solution to this is to promote a culture of moderation and mentorship which ensures that discussions are conducted in a tolerant way that allows newcomers to learn.

Another issue at this stage may the the technology used—for example, if all user support takes place on Usenet newsgroups, many people wont know how to access them, or the conventions they are expected to follow.  Using channels that new users will be more familiar with, such as web forums or social media, can help lower the commitment gradient here.

Reporting bugs

The step from discussing the project to reporting a bug can be high where the project uses a complex bug tracker, where there is an involved process to get access to the tracker, and where gathering the information required to submit a useful report involves intimate knowledge of the software.

The Ubuntu project lowers the gradient at this stage through use of the ubuntu-bug utility.  Any user can run the command:ubuntu-bug <software name>and have a template bug report generated with all the required information about their environment, and any relevant logs or crash reports.  All they then need to do is write a description of the problem.  Again, a culture of moderation and mentorship is useful here to help guide people into writing useful reports.

Submitting Patches

Submitting patches inevitably involves a step up in terms of effort, as the contributor needs sufficient knowledge of the programming language, the source code, a development environment and so on.  However, the commitment gradient can be made too steep if contributors are expected to follow a complex or poorly documented coding style, if they are expected to do a lot of manual testing before submission, and if the actual submission process is esoteric.

The main way to lower the gradient here is documentation, and automation where possible.  Coding styles should be well-defined and documented.  Tests should be automated using a unit testing tool.  The submission process should be well documented, using a well known workflow such as GitHub’s pull requests can help here.

The Moodle community has a tool called “code checker” which is packaged as a Moodle plugin, and allows developers to analyse their code to ensure it meets the project’s coding style.  This allows them to quickly identify and fix any issues before submission, and allows reviewers to quickly direct them to instructions on how to fix any discrepancies.

Taking Charge

Again, a large step up at this stage is inevitable, and in some respects desirable, as a project probably doesn’t want to be led by someone who hasn’t shown sufficient commitment.  There may also be legal requirements for the people in charge to adhere to.

However, excessive or unclear requirements for how a person might get voting rights within a project may make this step too large, so these need to be fair and well-documented.  Also, a leader will need to have a good understanding of the project’s governance model and its decision-making process, so these need to be well-documented too.

If an project is large enough, it may be possible to allow different levels of commitment at this stage, so not everyone who has a say on technical issues is also required to, for example, make budget decisions.

Written by Mark Johnson and originally published on OSS Watch. Republished using Creative Commons.

User profile image.
OSS Watch is an independent, non-advocacy service. We are experts on free and open source software, but we do not insist on it as the solution to every problem, nor are we tied to any particular solutions or providers.

2 Comments

Really interesting article which I will share, thanks. It seems to assume the natural path of progression is for developers only. As a non developer working in open source I have been involved up to the bug reporter point, but then gone off in the direction of writing documentation, managing plugin development, organising community events, even writing a book. A project needs to attract a variety of roles to flourish so it would be an interesting exercise to extend this commitment model to non developer roles. The model is a great idea, I'm involved in a new open source project at learning locker.net so will forward this around the team!

Hi Mark,
You're right that what I've described above is written in a way that applies mainly to developers, and that it's important for a project to attract a variety of roles, so thank you for bringing it up. However, I think the principles I've descibed are relevant to enabling all forms of contribution, they may just need to be applied differently.

For example, with documentation, you still have the steps of being able to raise issues with existing documentation and submitting improved documentation, for which you need simple, well-documented processes and support from other members of the community.

For more community-oriented roles like event organisation, having an open forum for suggesting ideas and improvements could help lower the gradient at the 4th stage, while a culture of mentorship, as with code contributions, helps lower it at the 5th. In this case, rather than coding styles you need to consider things like the culture of the community, perhaps ensuring that codes of conduct are well documented and so can be ahered to. Documentation can help too, keeping records of what worked well and what didn't in the past can help inform future organisers.

Many Thanks
Mark

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.