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!.


Becoming an Apache project is a process, not just a decision

June 1, 2011

Zdnet.com is talking about the ASF accepting or rejecting a new project – let me mention that this is not exactly how things work.

The only way to create new projects at Apache is through the Incubator, so if project FOO wants to join the Apache Software Foundation, that can only take the form of a proposal for incubation (see examples at http://wiki.apache.org/incubator/).

That proposal is then discussed and sometimes questioned by the Incubator PMC (Project Management Committee), in the open on the general@incubator.apache.org mailing list, until consensus is reached about the proposal and initial committers and mentors team.

A so-called podling is then created to manage the incubating project, and it’s only after successful graduation (based mostly on community aspects and “legal cleanliness” of the code and podling releases) that a project becomes a “real” Apache project.

So, becoming an Apache project is not just a decision of the Apache Incubator, it’s a process that can take from a few months to much longer, depending on the code base and on the community that forms around it.

Apache Subversion is an example of a project that zoomed through the Incubator, mostly because it was already operating like an Apache project, and its code already fulfilled Apache’s legal requirements. There are also many examples of podlings which stay way too long in the Incubator, either because their code or their community isn’t developing as it should.

ZdNet is speculating about OpenOffice in this case, so you’d think that such an important project would get a different treatment? I don’t think so – the Apache process and governance rules have been proven over time on a few earth-shaking projects already (like the HTTP Server, Apache Lucene, Apache Solr and Apache Hadoop to name a few), so I don’t think any project would get a special treatment – our current process works just fine.


+1! ™ – a rosy financial future for the Apache Software Foundation

April 1, 2011

Google recently announced their +1 button, which will without a doubt make the Internet a better place. What’s not to like +1?

As everybody knows the +1 concept has been invented at the Apache Software Foundation (ASF) – and it seems like there’s event an ASF patent pending on it. (Update: see also here, via @jaaronfarr). Our voting process makes extensive use of this simple and very effective concept.

If you do your math the bandwidth (and thus power, greenhouse gas, etc.) saved by using +1 instead of I agree in all our emails does make a difference for the planet – it’s not just a fun gimmick.

In recognition of this invention, usually well informed sources tell us, Google is going to donate 3.141592654 cents (yeah that’s Pi – they’re Google, you know) to the ASF every time someone uses their +1 button, starting today!

That’s excellent news for the ASF – as with any volunteer organizations, more funds mean more action, more power and more fun! I haven’t yet been able to estimate how much money those N*Pi +1 clicks represent in a year, but that’s certainly in the pile of money range.

A small downside is that we’ll need to use +1(tm), with the trademark sign, from now on. That’s a small price to pay for what looks like a rosy financial future for the ASF.

Very impressive move. thanks Google! The Open Source world should mark today’s very special date with a white stone, as we say in French.

+1(tm)!


Why the ASF disagrees with Oracle, straight from the Anonymous Coward’s mouth

November 16, 2010

An Anonymous Coward (as they call them) on Slashdot provides the clearest explanation I’ve seen so far.

I’m only quoting the original comment here, see the discussion on Slashdot for follow-ups:

The problem is that to be a compatible Java implementation you must pass the TCK. To get a hold of the TCK you must agree that your Java implementation has a limited field of use, namely desktop computers. That means you have to add a clause to your licence that tells your users where they can use the software – no such clause exists in any open source licence I’m aware of.

Sure you can use the OpenJDK, you can even fork it, but therein lies the problem… you can’t, because if you do and you want to claim it’s a compatible implementation you have to pass the TCK. So you have to licence the TCK, then you have to add a field of use restriction to your licence, but that’s incompatible with the GPL that the OpenJDK GPL requires you to licence under.

End result, you can have Oracle Java or ‘Open’JDK

The ASF don’t have a political axe to grind with the GPL, aren’t firing a salvo in some imaginary war based on their view of free; It’s about a contractual obligation Oracle has to release the TCK to the ASF. An obligation Sun had and failed to meet and that Oracle continues to fail to meet.

The ASF was re-elected to the JCP with 95% of the vote. No other elected member had anywhere near that. The members spoke with their vote and consequently the ASF leaving the JCP would be big news in a war with Oracle, nobody else. The ASF is outside core Java and the work of the JCP probably the biggest single contributor to the Java ecosystem. Their threat to leave the JCP would seriously damage it and Oracle’s commitment to opensource’s credibility.

You can only have Oracle Java or ‘Open’JDK – there’s no way out until Oracle honors the agreement.

I have also started collecting a list of links about the whole thing, at delicious.com/bdelacretaz/oraclemess.


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.


What Makes Apache Tick?

November 17, 2009

apachecon_us_09_twleung.jpgLooking at the diversity of Apache Software Foundation communities, one can see a recipe for failure: people from different cultural backgrounds, different mother tongues, different employers, different timezones…all working together to create some of the best software on the planet? You must be kidding.

How can this very loose collage of disparate people pump out dozens of high-quality releases every year, often working better than more structured corporate teams? This “mystery” has been on my mind for a while, and I have identified four drivers that influence the way we use collaboration tools that play a major part in our success.

The first driver is a common vision amongst project members. The Biblical saying, “Without a vision, my people perish” is quite valid for our projects. Both using a central development mailing list for each project, and spending time to collectively define our project’s charter, helps us foster this common vision amongst project members. Every member should have the same answer to the “what are our goals?” question, so it’s important to get them to talk in a central place, where they all get the same information, as opposed to undocumented, one-to-one discussions.

Secondly, providing real-time status updates to project members is key in helping them stay on track. At Apache, this is implemented by the many events generated by our collaboration tools: commit events to indicate code changes, issue tracker events to provide updates about the status of bugs and new features, success/failure events from continuous build systems, and standardized ways of announcing releases so that other projects are informed. Project members subscribe freely to as few or as many event channels that they want to, so as to stay on top of things in near real-time, and without having to actively ask others about what happened. Status meetings? No need for those, as the information is flowing all the time.

The third success driver lies in enabling real-time help requests. In an immediate crisis of the “we need to deliver this by tomorrow” type, especially when working with a big team, you need to be able to ask for help without necessarily 1) knowing who specifically will help, and 2) bothering others with direct person-to-person requests, especially if they work in a different timezone. The key here is using issue trackers, where one web page stores key data and parts of the dialog that leads to resolving an issue. Posting an issue on the tracker, with sufficiently detailed instructions about how to reproduce the problem, along with attributes such as severity level, affected modules, etc., is the best way to expose a problem to the group quickly and with precision. Using an issue tracker also allows you to quickly and efficiently change priorities as well as re-assign issues and tasks – key elements that make all the difference in a crisis.

Finally, having searchable archives of this information allows new project members, or those returning after a period of absence, to learn what transpired and why things have been done in a certain way. Without self-service archives, new participants would have to talk to everybody to find out about the project’s history, past decisions, conventions, etc., which is neither efficient nor scalable. Most of our archives are automatically built as project activities progress: mailing lists are archived, source code control history is kept forever, and issue trackers write the full history of the project’s micro-decisions.

Combined with Apache’s principles of meritocracy and consensus-based decision making, these four collaboration drivers allow our project teams to work very efficiently, and, in many cases, even more so than structured teams that do not establish those central hubs of information exchange.

Does your project team foster a common vision and provide tools for real-time status updates, real-time help requests and self-service archives to its members? If yes, congratulations: you’re on a good track to becoming as effective as an Apache project!

Many thanks to Sally Khudairi for reviewing and copy editing.

ApacheCon US 2009 picture by
Ted Leung / Creative Commons License (CC BY-NC-SA 2.0).

See also my Open Source Tools are Good For You presentation, which discusses the tools that Apache projects use to implement this.


What does Apache provide that other code repositories don’t?

November 16, 2009

People thinking about creating an open source project might rightly consider hosting on one of the various hosting services available: Google Code, SourceForge, kenai, bitbucket and github come to mind. Quick and easy, create a repository or request some resources and you’re in business.

Incubating a project at the Apache Software Foundation (ASF) takes a lot more effort than just requesting a hosting space on one of those services, so why would you do that? One can perfectly host code on one of those services with an Apache License, so what’s the difference?

I think the big difference lies in the governance model, and in fact calling the ASF just a code repository is very wrong. Let’s discuss some key elements of that.

The Apache voting process has been tried and tested since 1999, or even earlier. This is one of the things that projects coming through the incubator have to learn, led by their mentors. Learning is usually very easy as people quickly see the benefits of those simple no-nonsense rules.

The ASF also provides a well-defined structure for managing projects, and the foundation as a whole, in a fair and consensus-driven way. One could argue that structure gets in the way, and sometimes it does, but when things go wrong having a well-defined way of getting back on track helps tremendously. And this structure leaves a lot of freedom to the project’s management committee (PMC), there’s a lot of room for adapting a project’s way of working to its community and goals.

Creating an Apache project is certainly not required for all open source projects (and the foundation couldn’t scale to thousands of projects right now anyway), but for the critical infrastructure parts of one’s business (what’s sometimes called “open core”), having an established governance model makes all the difference.

The governance model is just one of the benefits that Apache projects get – there’s also the visibility, brand recognition, nice build services, and other tools, and, last but not least, the many friends that you make along the way! As everybody now knows, there are no jerks at Apache!