Collaborative Specification Development
Originally posted in the the February 2019 Eclipse Foundation Newsletter.
The Eclipse Foundation Specification Process (EFSP), which extends the Eclipse Foundation Development Process (EDP), defines a blueprint for collaborating on specification development in open source.
Committers are the ones who tend to develop most of the content. Committers have the ability to push their own contributions into their project’s source code repositories and decide whether or not to accept contributions from others. They are the ones that decide what goes into particular builds, and how content is distributed. Committers hold the real power in open source, and with that awesome power comes awesome responsibility. Committers serve the community as the ringmasters of collaboration.
Committers are members of what the EFSP calls the specification team, the first community that a committer serves. Committers on the specification team need to get along and ensure that they are collectively working towards the same goals. Collaboration within the specification team and the broader communities starts with transparency.
Be Transparent. The entire open source world shares a common definition of transparency. While there is some variety in degree, transparency is pretty simple to understand: specification teams must make sure that everybody can watch and understand what they’re doing. To this end, a specification team must use a publicly accessible source code repository that’s easy to find, use public facing issue tracking software, post their release plans where the community can find them, and capture meeting minutes in public forums (e.g. mailing lists with archives).
Individuals and groups engaged in producing compatible implementations form a community. The specification team’s committers need to work closely with implementers to ensure that the specification is meeting their needs and that the specification can indeed be implemented. The specification team needs the implementers: the EFSP requires that a version of a specification has at least one compatible implementation (under an open source licence) before it can be declared final and official. It’s expected that implementation teams will interact regularly (via open channels) with the specification team to provide feedback and ask questions.
The best thing that a specification team can do to help implementers is to be open.
Be Open. For a lot of open source communities, “transparent” and “open” mean the same thing (e.g. “open book”), but the EDP regards these terms as being quite different. For Eclipse projects, “open” means open to new ideas, or open to participation. The rules for participating in an Eclipse open source project must be the same for everybody: it’s not enough to just accept a few patches, a specification team has to be open to new ideas. It’s hard to be open. In short, the specification team has to let others in and give up absolute control.
It’s worth noting that representatives from groups developing compatible implementations are very likely committers on the specification team themselves and the specification committee. This is the desired state; in fact, it’s expected that committers will actively court implementers to contribute and, after demonstrating adequate merit, join the team.
Specifications have dependencies on other specifications. When one specification “depends-on”, “uses”, “includes”, etc. another specification, it’s natural and expected for the specification teams to work together to ensure that their products work together. Specifications that group together other specifications (referred to as “profiles” and “platforms” by the EFSP) provide a coherent overall story and so have a vested interest in ensuring that individual specification teams are working toward common goals. This is, of course, not easy: navigating the concerns of multiple consumers is always a challenge.
Coordinating the work of multiple specification teams requires collaborative planning.
Have a plan. It’s easy to lapse into a pattern of just letting development happen, but like any process (especially a specification development process), having some method to the madness is critical. A specification team must make sure that their project employs a development methodology and that somebody owns the process (e.g. a project lead). Having a plan helps developers know where they can contribute the most value and makes it easier for other specification teams, implementers, and users to implement their own plans.
Specifications that are closely related, or tightly coupled will likely share team members. Again, this is the desired state; specification teams are expected to actively court contributions from their consumers and work to turn those contributors into committers.
A specification needs implementers, and implementers need users. By extension, therefore, a specification needs users. For users, open source specification development breaks with tradition and opens up the process of developing specifications. Users can, and should, contribute to specifications and—just like with implementers—the specification project team should actively court their engagement and work to turn that engagement into contribution.
Specification teams must ensure that developers from all communities are welcome.
Keep the “Playing Field Level”. This doesn’t necessarily mean that a project team must let just anybody join the project, but rather that they must ensure that the same set of rules apply to everybody (the playing field may be level, but developers still have to earn their way onto the field). Some projects implement meritocracy, for example, by requiring that developers make some number of contributions to demonstrate that they understand the code, rules, and culture of the project before inviting them to join the team. Specification teams must make sure that the process for adding new developers to their team is well known and that the process is operated transparently (e.g. a public vote).
It’s easy to get overwhelmed when you try to think of managing interactions across all of these communities. In practice, however, there is considerable overlap across these communities and much of the collaboration occurs naturally. But real collaboration requires investments in time and energy from everybody involved.
The specification team’s job is equal parts developing specifications, building consensus in the community, and facilitating collaboration. We’re all in this together.