Lessons from “Producing Open Source Software”

The free book, Producing OSS / Producing Open Source Software, is one I’ve referred to now and again when thinking about how free/open source projects should be run and lately I’ve been thinking about how a big company like Red Hat works when they’re based around free/open source projects.

Here are some choice quotes that I think can serve as useful lessons for open organizations.

Handling Growth

Typically, all communications in an open source project, except sometimes IRC conversations, are archived. The archives are public and searchable, and have referential stability: that is, once a given piece of information is recorded at a particular address (URL), it stays at that address forever.

Use those archives as much as possible, and as conspicuously as possible. Even when you know the answer to some question off the top of your head, if you think there’s a reference in the archives that contains the answer, spend the time to dig it up and present it. Every time you do that in a publicly visible way, some people learn for the first time that the archives are there, and that searching in them can produce answers. Also, by referring to the archives instead of rewriting the advice, you reinforce the social norm against duplicating information. Why have the same answer in two different places? When the number of places it can be found is kept to a minimum, people who have found it before are more likely to remember what to search for to find it again.

Codifying Tradition

First, watch for patterns in how people get confused. If you see the same situations coming up over and over, especially with new participants, chances are there is a guideline that needs to be documented but isn’t. Second, don’t get tired of saying the same things over and over again, and don’t sound like you’re tired of saying them. You and other project veterans will have to repeat yourselves often; this is an inevitable side effect of the arrival of newcomers.

Stabilizing a Release

…the process of stabilizing a release is mostly about creating mechanisms for saying “no”. The trick for open source projects, in particular, is to come up with ways of saying “no” that won’t result in too many hurt feelings or disappointed developers, and also won’t prevent deserving changes from getting into the release…

The Release Owner

The group agrees to let one person be the release owner. This person has final say over what changes make it into the release. Of course, it is normal and expected for there to be discussions and arguments, but in the end the group must grant the release owner sufficient authority to make final decisions. For this system to work, it is necessary to choose someone with the technical competence to understand all the changes, and the social standing and people skills to navigate the discussions leading up to the release without causing too many hurt feelings.

In a typical non-open source project, the QA department or the client or product owner can function as the release owner, deciding whether certain features and bug fixes are good enough to get into release.

Share Management Tasks

This chapter in particular I really liked because almost all free/open source software projects are self-managing but that can get out of hand as the project gets larger or has more users (leading to more bug reports and feature requests).

The Patch Manager

The patch manager’s job is to make sure that patches don’t “slip through the cracks.” This is done by following every patch through to some sort of stable state. The patch manager watches every issue tracker discussion, pull request, or mailing list thread that results from a patch posting. If it ends with a commit of the patch, he does nothing. If it goes into a review/revise iteration, ending with a final version of the patch but no commit, he creates or updates a ticket to point to the final version, and to any discussion around it, so that there is a permanent record for developers to follow up on later. In projects that use a patch queue manager or review tool (e.g., Gerrit, Review_Board, etc), the patch manager can help encourage consistent usage of that tool, by putting patches there and watching to make sure developers handle them there.

When a patch gets no reaction at all, the patch manager waits a few days, then follows up asking if anyone is going to review it. This usually gets a reaction: a developer may explain that she doesn’t think the patch should be applied, and give the reasons why, or she may review it, in which case one of the previously described paths is taken. If there is still no response, the patch manager may or may not file a ticket for the patch, at his discretion, but at least the original submitter got some reaction. The true currency of open source projects is attention: people who can see that they are getting attention will keep participating, even if not every patch they submit lands.

The Documentation Manager

In most development jobs there’s no one designated as the person to take care of documentation and it falls by the wayside. This is also true of most free/open source projects. The documentation such as tutorials and manuals aren’t frequently updated. The book suggests assigning one person to the role of documentation manager, a dedicated role to ensure the documentation is reviewed and updated. A lot of projects would do well to find someone to take over this task.

Documentation patches are usually easier to review and apply than code patches. There is little or no testing to be done, and the quality of the change can be evaluated quickly just by examination. Since the quantity is high, but the review burden fairly low, the ratio of administrative overhead to productive work is greater for documentation patches than for code patches. Furthermore, most of the patches will probably need some sort of adjustment, in order to maintain a consistent authorial voice in the documentation. In many cases, patches will overlap with or affect other patches, and need to be adjusted with respect to each other before being committed.

Given the exigencies of handling documentation patches, and the fact that the codebase needs to be constantly monitored so the documentation can be kept up-to-date, it makes sense to have one person, or a small team, dedicated to the task. They can keep a record of exactly where and how the documentation lags behind the software, and they can have practiced procedures for handling large quantities of patches in an integrated way.

The Issue Manager

I also liked this part about an issue manager. Basically their role is to make sure the issue tracker doesn’t get flooded with duplicate tickets and to possibly assign tasks to developers who are responsible for certain parts of the project.

Issue managers can help map between tickets and individual developers. When there are a lot of bug reports coming in, not every developer may read the ticket notification mailing list with equal attention. However, if someone who knows the development team is keeping an eye on all incoming tickets, then she can discreetly direct certain developers’ attention to specific bugs when appropriate. Of course, this has to be done with a sensitivity to everything else going on in development, and to the recipient’s desires and temperament. Therefore, it is often best for issue managers to be developers themselves.

Depending on how your project uses the ticket tracker, issue managers can also shape the database to reflect the project’s priorities.

Writing it all down

At some point, the number of conventions and agreements floating around in your project may become so great that you need to record it somewhere. In order to give such a document legitimacy, make it clear that it is based on mailing list discussions and on agreements already in effect. As you compose it, link to the relevant threads in the mailing list archives, and whenever there’s a point you’re not sure about, ask again. The document should not contain any surprises: remember, it is not the source of the agreements, it is merely a description of them. Of course, if it is successful, people will start citing it as a source of authority in itself, but that just means it reflects the overall will of the group accurately.

Leave a Reply and Share Your Thoughts