'Working Open' Project Guide

  Edit

Working Open

Working Open is a means to an end. It should enable useful participation. Rather than a flood of comments from the peanut gallery, working open helps us be more agile, produces visible progress and momentum, and importantly, helps you maximize the amount of good you can do in the world with small resources (from "How To Work Open" by Matt Thompson).

Working open requires structuring efforts so that "outsiders" can meaningfully participate, and become "insiders" as appropriate (from Working Open, Mozilla Wiki. Practically, this means a mixture of tooling, process, and social norms.

Tooling

In his (highly recommended) book "Producing Open Source Software", Karl Vogel outlined some tools that every open source project needs:

Web site Primarily a centralized, one-way conduit of information from the project out to the public. The web site may also serve as an administrative interface for other project tools.

The website for Node.js is an example of a project website that points to it's other modes of communication, and points prospective developers and contributors to a place to download the source code immediately

Mailing lists / Message forums Usually the most active communications forum in the project, and the "medium of record."

Mozilla has hundreds of mailing lists for various software projects and activities. They are all archived using Google Groups - for an example, see the accessibility mailing list

Version control Enables developers to manage code changes conveniently, including reverting and "change porting". Enables everyone to watch what's happening to the code.

Git has become a very popular option for version control, and GitHub for hosting the version control system.

Bug tracking Enables developers to keep track of what they're working on, coordinate with each other, and plan releases. Enables everyone to query the status of bugs and record information (e.g., reproduction recipes) about particular bugs. Can be used for tracking not only bugs, but also tasks, releases, new features, etc.

Increasingly bug tracking and version control take place on the same platform. You can see the open issues for the Django Project on their code page, or those of Mozilla's Thimble Editor, where issues are tracked directly on GitHub.

Real-time chat A place for quick, lightweight discussions and question/answer exchanges. Not always archived completely.

Mozilla has used IRC extensively, and maintains a server that anyone can join. This is often the quickest way to meet a real human on the project. A popular alternative is Slack.

Process

The decision making process of open source projects needs to be carefully considered. If potential contributors are concerned that decisions will be made unilaterally, they may be hesitant to invest their time. Karl Fogel is again helpful here when encouraging hosts of open source projects to:

Avoid Private Discussions As slow and cumbersome as public discussion can be, it's almost always preferable in the long run. Making important decisions in private is like spraying contributor repellant on your project. No serious contributor would stick around for long in an environment where a secret council makes all the big decisions. Furthermore, public discussion has beneficial side effects that will last beyond whatever ephemeral technical question was at issue:

The discussion will help train and educate new developers. You never know how many eyes are watching the conversation; even if most people don't participate, many may be lurking silently, gleaning information about the software.

The discussion will train you in the art of explaining technical issues to people who are not as familiar with the software as you are. This is a skill that requires practice, and you can't get that practice by talking to people who already know what you know.

The discussion and its conclusions will be available in public archives forever after, enabling future discussions to avoid retracing the same steps.

Social Norms

It is important to make explicit that yours is a welcoming community. For example, the Mozilla Community Participation Guidelines state:

The Mozilla Project welcomes and encourages participation by everyone. It doesn’t matter how you identify yourself or how others perceive you: we welcome you. We welcome contributions from everyone as long as they interact constructively with our community, including, but not limited to people of varied age, culture, ethnicity, gender, gender-identity, language, race, sexual orientation, geographical location and religious views.

These types of document are often described as "codes of conduct". Another example is from the SASS framework.

Many software projects embed these codes of content within their codebase, so that they can be forked and added to in ways that create a "living document". An example of this can be found within the Angular project