Rules For Revolutionaries (2000 edition)

April 7, 2020

The below message is from 2000 but I think it still applies to open source collaboration in the 21st century.

I wasn’t part of the Apache Jakarta story myself but have heard of that a few times ;-)

It was written by James Duncan Davidson, I don’t take any credit for what follows – I just copied it back here from a public archive, to make it easier to find it next time I need to quote it.

Date: Thu, 13 Jan 2000 15:46:41 -0800
Subject: RESET: Proposal for Revolutionaries and Evolutionaries
From: James Duncan Davidson
To: general@jakarta.apache.org
CC: tomcat-dev@jakarta.apache.org

Ok, the logical place for this is general@jakarta, but I’m including tomcat-dev@jakarta so that the people who are there and not on general can see it. Please do not discuss on tomcat-dev, please only discuss on general.

In a closed source project where you’ve got a set team, you make decisions about where the entire team goes and somebody takes the lead of deciding what gets done when. In the discussions about Craig’s long term plan, this metric was applied by several of us in thoughts about where to go next.

After pondering this for a while, it’s (re)become obvious to me that there’s no way that anybody can expect an open source organization to work the same way that a team in a corporate setting can. Ok, so this is pretty freaking obvious, but I’ve been watching people that are not from Sun and who have been doing open source for a while talking and proposing things that come from this line of thought as well. Its not just people from Sun or people from any particular entity.

So — in any software development project there is a natural tension between revolution and evolution. In a closed source environment, you make the call at any particular time on whether you are in revolutionay mode or evolutionare mode. For example, JSDK was in evolutionary mode for years.
Then in Nov 98, We made a decision to go revolutionary. Of course, at the time the project team was composed of 1 person — me, so it was an easy decision. After that revolution was over in Jan 99, Tomcat was in evolutionary mode getting JSP bolted in and working with J2EE. We (Sun
folks) could do that because that was what suited the goals best at the time.

However, Open source is chaotic. With its special magic comes a different reality. This is:

1) People work on their own time (even people paid by a company can be considered to be working on their own time in this situtation as each company is going to have different cycles and things they want)

2) People work on what they want to. If you are working on your own time, you are going to do what you want or you do something else.

3) Some people are evolutionaries, other are revolutionaries, and some are both at different times.

4) Both approaches are important and need to be cultured.

5) You really can’t afford to alienate any part of your developer community. Innovation can come from anywhere.

To allow this to happen, to allow revolutionaries to co-exist with evolutionaries, I’m proposing the following as official Jakarta policy:

1) Any committer has the right to go start a revolution. They can establish a branch or seperate whiteboard directory in which to go experiment with new code seperate from the main trunk. The only responsibility a committer has when they do this is to inform the developer group what their intent is, to keep the group updated on their progress, and allowing others who want to help out to do so. The committer, and the group of people who he/she has a attracted are free to take any approaches they want too free of interference.

2) When a revolution is ready for prime time, the committer proposes a merge to the -dev list. At that time, the overall community evaluates whether or not the code is ready to become part of, or to potentially replace the, trunk. Suggestions may be made, changes may be required. Once all issues have been taken care of and the merge is approved, the new code becomes the trunk.

3) A revolution branch is unversioned. It doesn’t have any official version standing. This allows several parallel tracks of development to occur with the final authority of what eventually ends up on the trunk laying with the entire community of committers.

4) The trunk is the official versioned line of the project. All evolutionary minded people are welcome to work on it to improve it. Evolutionary work is important and should not stop as it is always unclear when any particular revolution will be ready for prime time or whether it will be officially accepted.

What does this mean?

In practice, this means that Craig and Hans and anybody else that wants to run with that revolution is welcome to do so. The only change is that it’s not called Tomcat.next — it’s the RED branch or GOOGLE branch or whatever they want to call it.

Whenever Craig (or anybody else working on that codebase) wants to bring stuff into the trunk, they propose it here and we evaluate it on it’s merits.

If somebody disagrees with Craigs approach (for the sake of argument here), they are free to create a BLUE whiteboard and work out what they think is a good solution. At that point, the community will have to evaluate both approaches. But since this is a populist society, with such a structure it is hoped that it becomes clear which is the preferred approach by the community by their participation and voting. Or maybe the best solution is something in the middle and the two parties work together to merge.

Irregardless, the point is to allow solutions to happen without being stalled out in the formative stages.

An important point is that no one revolution is declared to be the official .next until it’s ready to be accepted for that.

There is the side effect that we could potentially end up with too many revolutions happening, but I’d rather rely upon the natural inclination of developers to gravitate towards one solution to control this than to try to control it through any policy statement.

When would this be official?

Well, if this is well recieved, we’d want to word it up and make it a bylaw (with approval by the PMC — this is one of the areas in which the PMC has authority). Hopefully soon.

Comments? Suggestions?

James Davidson duncan@
Java + XML / Portable Code + Portable Data !try; do()


Open source is done. Welcome to Open Development!

December 14, 2017

I originally published this article on SD Times, republishing it to keep it around for posterity…

If you’re looking at embracing open source today, you might be a bit late to the game. Using open-source software is mainstream now, and being involved in open-source projects is nothing to write home about either. Everybody does it, we know how it works, its value is proven.

But what’s next? Sharing source code openly is a given in open-source projects, but in the end it’s only about sharing lines of text. The real long-term power of successful open-source projects lies in how their communities operate, and that’s where open development comes in.

Shared communications channels. Meritocracy. Commit early, commit often. Back your work by issues in a shared tracker. Archive all discussions, decisions and issues about your project, and make that searchable. All simple principles that, when combined, make a huge difference to the efficiency of our corporate projects.

But, of course, the chaotic meritocracies of open-source projects won’t work for corporate teams, right? Such teams require a chain of command with strictly defined roles. Corporate meritocracy? You must be kidding.

I’m not kidding, actually: Open development works very well in corporate settings, and from my experience in both very small and fairly large organizations, much better than old-fashioned top-to-bottom chains of command and information segregation principles. Empower your engineers, trust them, make everything transparent so that mistakes can be caught early, and make sure the project’s flow of information is continuous and archived. Big rewards are just around the corner—if you dive in, that is.

What’s open development?
Open development starts by using shared digital channels to communicate between project members, as opposed to one-to-one e-mails and meetings. If your team’s e-mail clients are their knowledge base, that will go away with them when they leave, and it’s impossible for new project members to acquire that knowledge easily.

A centralized channel, like a mailing list, allows team members to be aware of everything that’s going on. A busy mailing list requires discipline, but the rewards are huge in terms of spreading knowledge around, avoiding duplicate work and providing a way for newcomers to get a feel for the project by reviewing the discussion archives. At the Apache Software Foundation, we even declare that “If it didn’t happen on the dev list, it didn’t happen,” which is a way of saying that whatever is worth saying must be made available to all team members. No more discrepancies in what information team members get; it’s all in there.

The next step is sharing all your code openly, all the time, with all stakeholders. Not just in a static way, but as a continuous flow of commits that can tell you how fast your software is evolving and where it’s going, in real time.

Software developers will sometimes tell you that they cannot show their code because it’s not finished. But code is never finished, and it’s not always beautiful, so who cares? Sharing code early and continuously brings huge benefits in terms of peer reviews, learning from others, and creating a sense of belonging among team members. It’s not “my” code anymore, it’s “our” code. I’m happy when someone sees a way to improve it and just does it, sometimes without even asking for permission, because the fix is obvious. One less bug, quality goes up, and “shared neurons in the air” as we sometimes say: all big benefits to a team’s efficiency and cohesion.

Openly sharing the descriptions and resolutions of issues is equally important and helps optimize usage of a team’s skills, especially in a crisis. As in a well-managed open-source project, every code change is backed by an issue in the tracker, so you end up with one Web page per issue, which tells the full history of why the change was made, how, when, and by whom. Invaluable information when you need to revisit the issue later, maybe much later when whoever wrote that code is gone.

Corporate projects too often skip this step because their developers are co-located and can just ask their colleague next door directly. By doing that, they lose an easy opportunity to create a living knowledgebase of their projects, without much effort from the developers. It’s not much work to write a few lines of explanation in an issue tracker when an issue is resolved, and, with good integration, rich links will be created between the issue tracker and the corresponding source code, creating a web of valuable information.

The dreaded “When can we ship?” question is also much easier to answer based on a dynamic list of specific issues and corresponding metadata than by asking around the office, or worse, having boring status meetings.

The last critical tool in our open development setup is in self-service archives of all that information. Archived mailing lists, resolved issues that stay around in the tracker, source-code control history, and log messages, once made searchable, make project knowledge available in self-service to all team members. Here as well, forget about access control and leave everything open. You want your engineers to be curious when they need to, and to find at least basic information about everything that’s going on by themselves, without having to bother their colleagues with meetings or tons of questions. Given sufficient self-service information, adding more competent people to a project does increase productivity, as people can largely get up to speed on their own.

While all this openness may seem chaotic and noisy to the corporate managers of yesterday, that’s how open-source projects work. The simple fact that loose groups of software developers with no common boss consistently produce some of the best software around should open your eyes. This works.


Status meetings are a waste of time and money

November 23, 2017

Last Monday I presented on Asynchronous Decision Making at the (excellent) FOSS Backstage Micro Summit in Berlin and there were some questions about me saying that status meetings are a waste of time.

My opinion on status meetings hasn’t changed in a long time and I’m very happy to see Jason Fried loudly confirm it in his status meetings are the scourge post.

Quoting him:

How would you feel if you had to regularly expense $1200 so you could “tell a few teammates something”. Think that would go over well?

If your team shape allows you to run status meetings, you should first reflect on their actual cost. And if you still want to run them after that I suggest:

a) Requiring people to briefly report their status in writing before the meeting, asynchronously

b) Requiring people to read other people’s status before the meeting, asynchronously

c) Choosing a maximum of 3 items to discuss in your meeting,
based on those reports, and timebox those topics during the meeting

d) If you don’t get enough items to deserve interrupting your whole team right now: cancel that meeting! Or maybe limit it to managers to avoid interrupting the Makers.

That’s just the essentials, Jason Fried has more detailed suggestions in a similar spirit, make sure to read his post!

I like the 3P format for brief written status reports:

– Progress: what concrete, measurable progress has been made since last report

– Problems: what’s blocking you from progressing

– Perspectives: what are your plans for the next period

If this post (and Jason’s) help you save tons of money by eliminating useless meetings, feel free to make a donation to a good cause ;-)


Large Mailing Lists Survival Guide

November 10, 2017

I initially published this blog post on the Adobe Open Development blog at http://blogs.adobe.com/ but that’s been archived so I’m re-publishing it here for convenience. Thanks to Adobe for allowing me to spend a portion on my time reflecting on such topics!

Here’s a “survival guide” that we use at Adobe to help our colleagues make sense of our busy Open Development mailing lists.

To send or not to send

TS1. Before asking a question, search the list archives (and issue trackers, etc.) as the answer might already be in there.

TS2. Keep noise low – consider how many people will receive your message. If you’re just saying “thank you” to one or two persons, do it off-list.

TS3. Does your message really belong in an email? If it’s information that’s supposed to last and that you expect future coworkers to know, a wiki, website or blog post is a much better place. Just send the URL of that wiki/website page in email then. Writing more than 3-4 paragraphs is often a sign of something that does not belong in email. And email is where information goes to die!

TS4. Do not cross-post. If you really think other lists might be interested, let them know about your message by sending them its URL, but do not copy the message itself. Cross-posting tends to create split discussions that are impossible to follow.

TS5. Don’t be shy – if a mailing list exists it is meant to be used, so any on-topic question with a sensible subject line is welcome, assuming you do your homework as explained in this guide.

Starting new discussion threads

ST0. To start a new topic, do not reply to an existing message – use the “new message” function of your email client to create a new discussion thread.

ST1. When starting a new discussion thread, include at least one [TAG] in the subject line that points to the product, technology or topic that your message is about.

ST2. The goal of the subject line is to help people decide if they want or need to read your message. If that’s not sufficient, use your first phrase as a summary to clarify. On busy lists, spending time on crafting a good subject line avoids wasting other people’s time, and gives you much better chances to get an answer.

ST3. One question/topic per thread please, it’s much easier to follow, helps people notice your question and makes much more sense in the archives later.

Writing your message

WR1. The shorter your message or reply, the more likely people are to read it.

WR2. Speak in URLs – if something has an URL or unique identifier, point to it. Don’t say “the about page on the new website” or “the memory problem”, but rather http://www.example.com/about and SLING-9362 if the latter is a well-known shortcut to the URL of the actual issue in your tracker. This helps avoid misunderstandings, as well as creating valuable archives with a rich Web of links.

WR3. If you’re describing a bug, include all the necessary information to reproduce the problem, while being as concise as you can: what did you do, what did you expect, what did you get, what was your environment.

WR4. No large attachments or stack traces: open a bug with that info or put it somewhere where people can download it and include only the URL in your message.

WR5. Be direct, ask the root question instead of a derived one. If you need to buy food at 4AM, for example, and you think Burrito Unlimited might be open, asking where can I buy food now is more likely to provide a helpful response that asking where the nearest Burrito Unlimited is. Also known as an “XY problem” where you ask Y but what you really need is X.

Replying and quoting

RQ1. Quote sparingly and precisely. Opinions differ on this, but the lazy top-quoting that’s unfortunately the norm depending on which email client you use tends to make discussions shallow, as it’s impossible to know precisely what people are replying to. So many years later, Usenet quoting still rules on busy lists and/or for complex discussions.

RQ2. Give sufficient context for people to follow your thoughts. Closely related to precise quoting.

RQ3. Remember WR1 – the more concise message usually wins.

Filtering tips

Here are some tips for coping with many emails from multiple high-traffic lists. The goal is to give you the option to quickly skim over the lists traffic to find the few threads that are actually relevant to you.

F1. Have a folder for each list, and a filtering rule that moves the relevant messages there.

F2. To make sure you quickly see responses to threads you take part in, have a special rule for emails/threads that include you. This is a rule that you can have across all your emails: it could be a special “to me” folder, or a different inbox.

F3. To filter out the topics that interest you, set up a rule based on keywords in the subject. Same for people.
This works especially well if people consistently use the ST1 subject line tags mentioned above.

See Also


The Five Wisdoms of Open Development

February 15, 2013

Preparing my Open Development in the Enterprise talk for ApacheCon NA 2013 in Portland the week after, I’ve tried to capture the basic wisdoms of day-to-day work in an Open Development environment:

If it didn’t happen on the dev list, it didn’t happen.

Whatever you’re working on, it must be backed by an issue in the tracker.

If it’s not in the source code control system, it doesn’t exist.

If it’s important, it needs a permanent URL.

What happened while you were away? Check the activity stream and archives.

As usual, following recipes without understanding what they’re about won’t help – I use those wisdoms just as a reminder of how things are supposed to happen, or more precisely how people are supposed to communicate.


Open Source Communites are like gardens, says Leslie Hawthorn

June 4, 2012

Great keynote by Leslie Hawthorn at Berlin Buzzwords today – here are my quick notes.

As with a garden, you need to cultivate your community, it doesn’t just happen.

You need to define the landscape – where you want the garden to grow. For a community this means clearly defining goals and non goals.

The landscape needs to be regularly assessed – are we welcoming to newbies? Can new plants grow here?

Clear the paths. Leslie mentions the example of rejecting code patches based on the coding style – if you haven’t published a style guide, that’s not the best way to welcome new contributors. Make sure all paths to success are clear for your community members.

A garden needs various types of plants – invite various types of people. Not just vague calls for help – specific, individual calls based on their skills usually work much better.

Pluck out the weeds, early. Do not let poisonous people take over.

Nurture your seedlings. Take care of newbies, help them grow.

Like companion planting, pairing contributors with the right mentors can make a big difference.

Know when to prune. Old-timers leaving a project is not necessarily a problem, things change.

Leslie cites OpenMRS as an example of successful community management – I’ll have to have a look but I already like the “how to be a casual committer” paragraph in their different types of OpenMRS developers page.

All in all, very interesting parallels. Being quite clueless about gardening, I never thought of looking at our communities from this angle, but it makes perfect sense. Broadening one’s view – that’s what a keynote should be about!


Stefano’s Mazzocchi’s Busy List Pattern

December 6, 2011

Since being part of a larger company, I’m hearing people saying “we need a new mailing list for that” way too often.

People are afraid of busy mailing lists sometimes, but in terms of fostering open collaboration and communities a busy list is excellent.

Another problem is people writing 1-to-1 emails instead of writing to the list, as an attempt to avoid making the list even noisier. If your message is on-topic with a well written subject line, and as concise as possible, it’s not noise and definitely belongs on the list.

Stefano’s Mazzocchi briefly explains this in his ApacheCon 2006 slides titled all you wanted to know about Open Development community building but didn’t know who to ask. I haven’t found that pattern described in a more accessible way than among Stefano’s 303 PDF slides so far, so here’s a summary that I hope is faithful to the original idea.

The Busy List Pattern

Here’s my summary of that part of Stefano’s slides (starting at page 200 in his PDF file), with some additional comments of mine.

The pattern starts with somebody suggesting that the mailing list is too noisy and should be split in multiple ones.

Restaurants and night clubs, however, know that packed rooms help marketing…what’s more boring than being alone in a restaurant?

But we’re not a bar…we can’t go on getting 200 messages on that list every day, can we?

Actually we can…if everybody who posts to the list is extra careful about how they post, a list with 200 or more messages per day is perfectly manageable – but only if the subject lines are very carefully chosen and evolved (see below), and only if people are very careful about what they post, to maximize clarity and avoid wasting other people’s time.

We should strive to keep our lists as packed as possible. It’s hard to set a limit, but before splitting a list you might ask if people are using it efficiently. First try to improve the signal to noise ratio, and if that really fails you might consider splitting the list.

If you really need to split the list, do it by audience and not by topic – a consistent audience will lead to an interesting list, whereas scattering topics all around makes cross-topic discussions painful.

Careful with those subject lines

The subject line of messages makes all the difference between a noisy list an a useful one.

Choose sensible subject lines that allow people do decide if they want to read your message or not.

Reread your subject line before sending – does it really express what your message is about, and does it contain any relevant call to action?

Change those subject lines when the thread changes topics.

Address one topic only per thread.

Use [MARKERS] in subject lines to tag messages.

Simple rules like this will boost your list’s efficiency tremendously – there’s more good stuff like this in Stefano’s slides, make sure to have a look!

Update (8 years later…this is still as valid as ever!): my survival guide has more guidelines on how to cope with large mailing lists.