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!


How to fix your project collaboration model?

August 5, 2011

I’ve been studying the collaboration processes of the Apache Software Foundation (ASF) for a while [1], by observing and practicing the successful collaboration model that we use in ASF projects.

Taking the opposite angle, I’ve been reflecting lately on how to fix a broken collaboration model. How do you help teams move from an “I have no idea what my colleagues are doing, and I get way too much email” model to the efficient self-service information flow that we see in ASF and other open source projects?

As I see it, the success of the Apache collaboration model is based on six guiding principles:

  • If it didn’t happen on the dev list, it didn’t happen.
  • Code speaks louder than words.
  • Whatever you’re working on, it must be backed by an issue in the tracker.
  • If your file is not in subversion it doesn’t exist.
  • Every important piece of information has a permanent URL.
  • Email is where information goes to die.

Some of those might need to be slightly tweaked for your particular context, but I believe you can apply most of them to all collaborative projects, as opposed to just software development.

The context of an ASF project is a loose group of software developers, architects, testers, release managers and users (with many people playing several of these roles) working remotely, with no central decision authority. There’s no manager in an ASF project, no money exchanged and no common corporate culture. Decisions are made by consensus, by a group that grows organically as new members are elected based on their merit with respect to that particular project.

This may sound like a recipe for failure, yet many of our projects are very successful in delivering great software consistently. How does that work?

Let’s describe our six principles in more detail, so that you can see if they apply to your own project.

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

In an ASF project, all decisions are made on a single developers mailing list.

Backchannel discussions are inevitable: someone will meet a coworker at the coffee machine, people attend conferences, talk on IRC, etc. There’s nothing wrong with that, but the rule is that as soon as a discussion turns into something that has impact on the project, it must come back to the dev list. The goal is for all project participants to have the same information from a single source.

As those lists are archived, you can then go back to check why and how a particular decision was made.

Creating consensus using email only can be hard, on the other hand it forces you to clarify your ideas and express them in an understandable way, which in the case of software often promotes cleaner architectures and designs (but see also code speaks louder than words below).

Email etiquette (solid and evolving subject lines, concise writing, precise quoting etc.) plays a big role in making this work, and that’s something people have to learn.

In an ASF project, experienced members will often help beginners improve their list communications skills, by gently steering them towards more efficient writing and messaging styles. And your message might just be ignored if the subject line says “URGENT: need help!” or “Question”, which can be a good beginner’s lesson.

Top-posting is usually frowned upon on ASF lists, as that often leads to superficial discussions compared to the much more precise inline quoting.

Email is where information goes to die.

Aren’t we contradicting the previous principle here?

Not really – the dev list is for the flow of discussions and decisions, not for important information that people need to refer to in their work.

Even with good and multiple email archives like the ones we have for ASF projects, finding a specific piece of information in email is painful. That might be good enough for going back to a discussion to get more context about what happened, and to go back to decisions (marked by [VOTE] in their subject lines at the ASF) from time to time, but definitely not for the day-to-day information that you need in such a project. That’s where the issue tracker, discussed below, comes into play.

Code speaks louder than words.

No one told me that when I started working in ASF projects, but after some time trying to argue about software architecture and how my ideas would improve our project’s software, I realized that I was just wasting my time.

The best way to express a software architecture or an idea that will improve a software component is to implement it and show the code to your fellow project members.

That code might be just a rough and ugly prototype in any suitable programming language, that’s not a problem – as long as it expresses your ideas, you will often spend much less time getting that idea across when it’s backed by a concrete piece of code.

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

This might be the most important of our guiding principles – on a desert island, I think I’d be ready to work with just an issue tracker as my collaboration channel.

Many people think that issue trackers are only for bugs: you create an issue when you have run your software and found something that doesn’t work.

Although that was the original intention, I believe (and I’ve seen this fly in many different contexts) that an issue tracker can be used to back all the work that’s being done in a software or other project. Software design, implementation, test servers and continuous integration setups and maintenance, hardware upgrades, password reset requests, milestones like demos and sprints (as issues, not just dates)…and bugs of course: managing all project tasks in a single tracker makes a huge difference.

When used as your coordination backbone, a good issue tracker (we currently use JIRA and Bugzilla at the ASF) will help answer a lot of questions about your project’s status, such as

  • Who’s working on what?
  • What did Joe Developer do last month?
  • Where do we stand?
  • What prevents X from being implemented?
  • Why did we implement X in this way back in 2001?

For this to work, project members need to update their issues often, and break them down into smaller issues as needed, so that the tracker later tells the story of how the task went from A to B.

No need for big literary statements, but instead of sending an email to the dev list saying that X is ready to be used, just update the corresponding issue in the tracker. A good tracker will send events when that happens, to which people can subscribe. Together with the source code control system events (commits etc.) this creates a live activity stream for your project. Making extensive use of the tracker will help provide a complete picture of what’s happening, in that stream.

I’m also a big fan of using issue dependencies to organize issues in trees that can be used to keep track of what needs to be done to reach the project’s goals (aka “planning”, but in a more organic form).

Cygwin dependency treeAs an example, here’s the dependency tree for bug 3383 of the cygwin project. That’s not an ASF project, which shows that we’re not the only ones to use this technique.

That tree starts with “the FRYSK project” as an umbrella issue, which is broken down into issues that represent the different project areas, and so on util it reaches the actual things that need to be implemented or fixed. Combined with a tracker’s reporting functions, such a tree helps tremendously in answering the “where do we stand?” question, and in reshuffling priorities quickly in a crisis. You can also create umbrella issues for sprints or releases, to express what needs to be done to get there.

If your file is not in subversion it doesn’t exist.

The goal here is to avoid relevant files floating around – put everything in subversion, or in whatever source code control system you’re using.

If some files are really too large for that, make sure they have permanent URLs, and document those in the issue tracker or in your source code.

Every important piece of information has a permanent URL.

If you cannot point to a piece of information with a URL, it’s probably not worth much. Or you’re using the wrong system to store that information.

I also like to speak in URLs as much as possible. Saying SLING-505 (which is an agreed upon shortcut for https://issues.apache.org/jira/browse/SLING-550 in an ASF project) is so much more precise than referring to the background servlets feature.

Conclusion

Reviewing your collaboration model against the above principles should help find out where it can be improved. The most common problems that I’ve seen in the various organizations that I worked for in my career are the “split brain” problem, where testers, customers or managers use different tracking systems, and the “way too much email” problem where people send important information (or code…aaaaarghhhh) around in email as opposed to taking advantage of a tracker.

Does that sound like you? If yes you might want to have a closer look at how successful open projects work, and take inspiration from them.

[1] See previous posts: What makes Apache tick? and Open Source collaboration tools are good for you!.


On speaking in URLs

December 3, 2010

speaking-in-urls-2.jpgI’ve seen about five examples just today where speaking in URLs (I spoke about that before, slide 27) would have saved people from misunderstandings, and avoided wasting our collective time.

When writing about something that has an URL on a project’s mailing list, for example, pointing to it precisely makes a big difference. You will save people’s time, avoid misunderstandings and over time create a goldmine of linked information on the Web. It’s not a web without links, ok?

Writing https://issues.apache.org/jira/browse/SLING-931 (or at least SLING-931 if that’s the local convention) is so much clearer than writing about “the jcrinstall web console problem”. You might know what the latter is right now, but how about 6 months later when someone finds your message in the mailing lists archives?

Of course, all your important technical things have stable URLs, right?


Twitter is the new CB…but it’s missing the channels!

September 29, 2010

When I was a kid, Citizen Band Radio (aka “CB”) was all the rage if you could afford it.

Those small unlicensed two-way radios have a relatively short range, actually extremely short if you compare to the global range of Twitter today. And they don’t have that many channels, 40 in most cases if I remember correctly. That works as long as the density of CB users is not too high in a given area.

For general chat, CB etiquette requires you to start by calling on a common channel for whoever you want to talk to, and, once you find your partner(s), quickly agree on a different channel to move to, to avoid hogging the common channel.

That “agree on a different channel to move to” feature is key to sharing a limited medium efficiently. As the Twitter population grows, the timeline that I’m getting is more and more crowded, with more and more stuff that I’m not interested in, although I’m willing to follow the general flow of a lot of people.

The global reach of services like Twitter and ubiquitous Internet access makes CB mostly obsolete today.

Twitter is the new CB, in many ways.

What Twitter lacks, however, are the channels, as in:

Could you guys at SXSW move to the #c.sxsw channel and stop boring us with your conference chitchat? We’re jealous, ok? Thanks.

Direct messages don’t work for that, as they are limited to two users. A bit like a point-to-point channel, like the telephone, as opposed to multipoint as the CB provides.

Twitter channels can also be very useful for data, like weather stations or other continuous data sources that can benefit from hierachically organized channels. But let’s keep that discussion for another post. Like my mom said, one topic, one post (not sure it was her actually).

What does Twitter need to support channels?

I think the following rule is sufficient:

Any message that contains a hashtag starting with #c. is not shown in the general timeline, except to people who are explicitely mentioned with their @id in the message.

Such messages can then be retrieved by searching for channel hashtags, including partial hashtag values to support hierarchies.

Using hierachical channel names by convention opens interesting possibilities. The ApacheCon conference general channel would be #c.apachecon for example, the java track #c.apachecon.j, etc.

This channel filtering could of course be implemented in Twitter clients (@stephtara, remember you said you were going to mention that to @loic?), but in my opinion implementing it on the server side makes more sense as it’s a generally useful feature.

Then again, I’m a server-side guy ;-)

Opinions welcome, of course.


This is how we work at Apache

July 16, 2010

I just had to (re-)explain how the Apache way of working makes a difference by enabling a continuous flow of information between developers.

No more begging for reports, no more boring meetings where you only exchange information: who could say no to that?

Here it is for your enjoyment. This is the same thing that I’ve been saying in my recent talks on this topic, reduced to the bare minimum.

  • All technical discussions and decisions on public mailing lists.
  • Speak in URLs: if you reference something (discussion, vote,
    code…anything) include its URL, which must be permanent.
  • Shared code repository, commit early, commit often (as in: daily at least, from day one)
  • Commit events sent to mailing lists and/or RSS feeds to which people
    can subscribe.
  • Shared issue tracker and “if you’re working on something it must be
    an issue in the tracker”
    so that progress reports are automatic. Also generates mail/RSS events.
  • Commits are linked to tracker issue IDs – by speaking in URLs in your commit messages, mostly.
  • Automatic archiving of all this information, for self-service access.

All this is public and centrally accessible of course, so everybody
gets the same information.

The main reluctance that I see when trying to convince people to work
in this way is the fear of exposing your mistakes and initial bad
designs in public. My answer is to just get over it: you’d find tons
of such blunders if you were to analyze my work at Apache in the last
ten years, yet I’m reasonably alive and kicking.


Follow

Get every new post delivered to your Inbox.

Join 30 other followers