THE OPEN SOURCE WAY 2.0

A community is a group of people united by a common identity and collective purpose who engage in activities together over time. Communities develop unique sets of shared values, principles, and norms that distinguish them from others and provide members with a sense of belonging.

An open source software community is a group of people united by the shared purpose of developing, maintaining, extending, and promoting a specific body of open source software. These communities are often globally distributed—their members occupy different geographic regions and work across numerous industries. What unites them is their common vision for the open source software project—as well as the spirit of camaraderie and collective identity that participating in the community affords them.

The community-driven ecosystem of open source software is vast and difficult to visualize, so many developers tend to describe it metaphorically, preferring the language of waterways and tributaries. Software that forms the foundation of other software is said to exist "upstream" from that software. When "upstream" software undergoes changes, those changes flow "downstream" to the open source projects that rely on them. When programmers working "downstream" create innovations that might benefit others, they can submit those changes "upstream" to their parent projects, so those improvements can ripple outward to everyone utilizing those same upstream projects.

Red Hat Enterprise Linux, for example, exists "downstream" from many open source software projects that comprise it, such as Fedora and CentOS Stream. Those projects, in turn, rely on additional "upstream" projects—like the Linux kernel, the GNOME desktop environment, and hundreds more.

Open source software communities form when people agree to work together to build and improve software. For this to occur, a person or group building software must make that software available to others—by releasing the software’s source code and expressly giving others permission to copy, modify, and redistribute it (typically under the terms of a specific open source license).

Because open source communities are globally distributed, they typically form online through the shared use of electronic mailing lists, forums like Discourse, and code-sharing platforms like GitHub.

Most open source software communities don’t have formal membership applications or approval processes. More commonly, people get involved in projects simply by contributing to them in some way—for example, by fixing bugs in software code, creating new features for an application, writing and editing documentation, creating logos and graphics, promoting adoption of the software, representing the project at a conference and other events, or assisting others who have questions about the software.

In short, people earn membership in open source software communities by virtue of their contributions to those communities and the positive reputations they establish as a result of those contributions.

People join open source software communities for many different reasons.

Many join because working on the software is part of their jobs—either because their organizations hired them to develop it, or because their jobs depend on the software working well. They join communities so they can directly impact the development of software on which they (or their organizations) rely for critical operations.

Other people join because communities offer opportunities for them to sharpen their skills by working alongside and learning from others.

Some join because doing so allows them to collaboratively solve a problem they’re experiencing.

Some join because of their belief in the importance of contributing to a common set of resources beneficial to everyone. And others join for the purpose of socializing, or for a sense of identity and affiliation.

Organizations increasingly rely on open source software applications for various critical operations, as much of the world’s most innovative and effective applications are open source. So they participate in open source software communities because they’re invested in the long-term viability, stability, and security of those applications—and, often, because they want to influence development of those applications' features and functionalities.

Other organizations participate in open source software communities because they’d like the software they’ve developed to become an industry-wide standard—they open their work in the hope that others will more quickly adopt and integrate it.

Many organizations find that participating in open source software communities allows them to access a wider talent pool than they could if they developed their applications entirely in house.

Consider engaging an open source community using the same approach you might take when you move into a new neighborhood. Introduce yourself and work to understand the community’s history, values, and dynamics before proposing big changes.

Make new friends by performing small jobs. Fix bugs in source code. Edit documentation. Build installation scripts. If your organization is able to allocate additional resources to support the community, consider sponsoring that community’s activity at events or hiring community developers so they’re able to spend more time working on the project.

Just note that arriving in a community with more people than it can comfortably welcome at one time may elicit a reaction from the community, which can be counterproductive to an organization’s long-term goals. And choose your organization’s initial participants in a community wisely. Individuals—not organizations—join open source communities, and the trust one participant garners is not automatically transferrable to another person or organization.

Many companies are in this position. These companies have determined that collaborating on mutually beneficial software applications or standards is more valuable than competing to develop different, perhaps incompatible, technologies. Instead, their business models involve building market-differentiating and revenue-generating innovations on top of these shared technological foundations.

Getting involved in an open source software community has important organizational, procedural, and legal implications for an enterprise. Most organizations that are seriously invested in open source software development fund internal open source program offices (OSPO) to advise the organization on matters related to open source community participation. Others partner with open source experts to advise this work.

This should be a very basic question. But its answers typically aren’t. Too often, open source projects describe themselves in terminology unfamiliar to many potential users, or they focus on how they do what they do, rather than on the problems they can solve. When formulating potential answers to this question, focus them on how the project helps its users. What problem does it solve? How would you describe your project to a potential user of the project in the most succinct terms possible?

For example, let’s imagine we’re asking an Istio developer what Istio is. The most basic answer is "it’s a service mesh." One might argue, however, that most container application developers don’t entirely understand what a "service mesh" is. So the shorthand description—"It’s a service mesh!"—doesn’t help a novice understand if or how to use it. A better explanation might involve describing Istio in terms of an application data plane and control plane (if I am talking to someone from the networking world), or perhaps a concept of traffic cops assigned to components of an application (if I am explaining the project to someone unfamiliar with the concept of a service mesh).

Ask as many follow-up questions as your community needs in order to develop a simple, straightforward understanding of project and what it can do.

Many open source projects do not clearly understand who uses their projects and what those users do with the project’s tools. Consider using the concept of "personas" to characterize archetypal groups of key users, and be sure to think in terms of "jobs to be done."

You might categorize a project’s potential or current users with a number of criteria:

Answers to these questions will influence the priorities your community sets for structuring the project, promoting it, and even the degree of engineering effort you’ll invest into certain features. For example, if your project runs in a datacenter or on a cluster of servers, your audience will typically be a business audience—people running IT professionally (or as a volunteer in a university). For a mobile application or a web development framework, the majority of your audience will be running your project on their personal computer, workstation, or cellphone. Each of these groups has different resource prerequisites, and the problems motivating their use of the project and its tools are different.

Moreover, anyone interested in developing an open source product strategy should think additionally about the critical relationship between project users and product buyers. A company’s path to adopting open source doesn’t usually follow a straight line from use of an upstream open source project to conversion to an enterprise open source product. Open source adoption tends to be "grassroots," bottom-up; enterprise open source products are often evaluated and purchased top-down. Those adopting an open source project inside a company can be valuable influencers when consulting on purchasing decisions—if they’re connected to the purchasing process, or if the person responsible for purchasing is aware that the company is already using the product.

Once people are turning up to your project, engagement is key to growing the project’s user base and community. You can engage with users in multiple ways, each requiring different degrees of effort and resulting in differing outcomes.

Figuring out where you should focus your efforts can be difficult. So it’s useful to take stock of all of the ways you’re currently engaging with project users in order to identify blind spots and opportunities for improvement. Consider characterizing engagement techniques as "low-," "medium-," and "high-touch" (terminology borrowed from sales). Low-touch methods represent very little interaction between potential users and your community, while high-touch methods represent one-to-one or one-to-few efforts.

Here are some examples of the types of things you can categorize this way:

Ideally, your project will have a healthy mix of each of these. Working on your website, documentation, and promotional materials allows new users to act autonomously and without much help from a senior community member. Your bug tracker, mailing list, and forum provide opportunities for community members to engage with your community, ask questions, and provide feedback. This kind of activity provides an opportunity to learn more about how people are using your project. Finally, high-effort activities like training, conference booth attendance and follow-up, and in-person conversations can be extremely valuable on a one-on-one basis—but those techniques do not scale well.

The "sales funnel" model may be useful to communities thinking about engagement activities and project goals.

Low-touch activities are good for raising awareness of your project and getting people to look at it for the first time. Ensuring your web site and other materials clearly communicate what the project does, how it can help users, and how contributors can try it out and get started quickly is paramount. Medium-touch activities are great for creating a "center of gravity" around your project—not only making communication with users possible but also enabling those users to help each other (hopefully generating a network effect). And high-touch activities are great for building relationships with key community users, gathering community case studies, and helping larger groups be productive with and become advocates for your project.

A key consideration for groups crafting potential engagement pathways is how someone unfamiliar with the project might start using it and, over time, gain seniority in the project to the point of becoming a core contributor.

You can tell a lot about a project by assessing who that project competes with, or what other projects people use to accomplish the same (or similar) tasks. Consider asking:

Analyzing your competition can help you begin answering a number of key questions early in a project’s goal-setting process, and answering these questions will help when your community begins prioritizing features and deciding how to contact potential users. Perhaps, for example, you can piggy-back on existing gatherings between people already interested in a competitor’s technology and spread your message there. Or if you’re an upstart disruptor, your goals and messaging may be anchored to your competition: "cheaper than," "an open source alternative to," "simpler and faster than." If you’re in a new market and your project is involved in a "land grab," you’ll need to focus on spreading your message fast—which means a higher marketing budget or more aggressive community plan, and more focus on defining the problems you solve for potential users.

If your software is frequently consumed with or is particularly useful to users of another project, then you may see opportunities for growing awareness of your project in its early stages and better understanding your users' needs. For example, Ceph can manage storage for OpenStack or Kubernetes; for Ceph, then, OpenStack and Kubernetes are adjacent communities. Catering to adjacent projects to find an audience may affect your technology roadmap, the events you target, the effort you put into specific integration projects, and so on. An adjacent project provides you with a potentially friendly audience who have the same problems your technology solves, so you can engage in some joint market research or UX testing, or coordinate joint events to meet and engage with potential users. This is also connected to understanding your competition; the communities important to them will also be important to you.

The existential question for every open source project is: "Why does this project exist?" Specifically, for a project released by or driven by a vendor, that question becomes: "What do we want to achieve by investing in this project?"

Surprisingly, many projects have difficulty answering this question.

As a vendor, ask: Why did you open source this piece of software in the first place? Are you trying to grow a market, promote a standard, disrupt a competitor, or increase demand for another product in your portfolio? Each of these requires a different message and different set of investments.

Understanding the reasons for open sourcing your project will help you clarify the investment required to achieve your goal remain aligned across engineering, product, and sales teams down the road. In the absence of a strong common vision for the project’s goals, you may find yourself under-funding the open source project, in part because of perceptions that it competes with products you build on top of it. A good open source product strategy provides clarity on which markets you are targeting, the market segmentation between product and project, and the role that the project plays in your entire business strategy and product portfolio. Clarifying these things will pay dividends in future discussions concerning the technical roadmap, or the relative prioritization of community promotion versus sales lead generation.

A small number of people who will care deeply about your project, and can represent a group of people or interests which affect the project. These people are your stakeholders.

In the case of vendor-sponsored projects, this group typically includes an engineering lead, product management, product marketing, and a representative of the field (field engineer, sales). You may also want to include in this group someone from your content services or support organizations and someone from product security. This is the group of people you will brief to prepare a stakeholder review, and you should gather them once every six to 12 months to check in on the state of the project and ensure alignment on the goals and the required investments to achieve those goals.

Answers to these seven questions can furnish a single-page document that forms a baseline, a frame of reference, for any project planning conversations. After running this exercise, your team or community should share some understanding of the problems your project solves, and for whom. You will be able to communicate the value of your project in language that makes sense in your potential users' frame of reference. You will understand how your project fits into a market, and what you want to achieve with it there. Finally, you will have identified the key group inside your organization who should be aligned on your current status and future strategy.

Combining the answers to these seven questions, next steps for your project should become obvious to all involved—and your community will be ready to help your project succeed in achieving its goals.

People must understand the "who," "what," "where," "when," "why," and "how" of working with an open source software community. Thoughtfully established and well-maintained communication channels enable open source project and its participants to:

As you develop project documentation and other informational resources, recognize this work has several different audiences. Understanding these audiences and prioritizing their unique needs can help you craft better materials.

For example, consider the basic distinction between project users and project developers. Someone interested in using the software will be interested in things like how to install it, how to configure it, and what they need to know to accomplish the task at hand (e.g., build a website). Developers will also be interested in such details, but will need additional detail if they are going to contribute effectively to the project.

If your project observes certain coding conventions, be sure to include those conventions in the developer documentation. Having a patch rejected by a maintainer because you haven’t indented code a certain way can be rather demotivating. Users, however, likely won’t need these details.

Include a simple overview of the project in an easy-to-spot location on the project website. This project description should include what the code base is designed to do and what problems someone might solve by using it. Making this information succinct and easy to find is critical. Post a quick description on the project’s home page so that interested parties immediately discover if the project is designed to meet their needs.

Think of this information as the opportunity to explain to someone who has never heard of your project why it could matter to them—in 30 seconds or less. For example, Drupal’s about page describes the project this way:

In this description—just a single paragraph—we learn:

Let’s take another example from a popular project: Kubernetes.

When visiting the project home page, kubernetes.io, a visitor immediately sees the following explanation:

In this description, we immediately learn:

The processes for creating good "getting started" documentation—occasionally called "onboarding documentation"—are outside the scope of this chapter. (Refer to the dedicated onboarding chapter in this guidebook for more detail.) Here, suffice it to say that open source project websites should feature a section aimed at helping new users and potential contributors get started using the software. Clearly labeling that section "getting started" or "new users" makes finding that section easy when people need it. Further differentiating between "new users" and "new contributors" in your onboarding documentation is even better, as these two audiences have very different needs. Clearly pointing to these resources for newcomers on the project website helps to keep the project’s other communication channels—like the forums and real-time chat rooms—free from frequently repeated inquiries about how to get started.

Another excellent location to feature basic information about your project is a frequently asked questions (FAQ) page. If project development is just beginning, a basic FAQ detailing what the project is, what the code base is used for, and how someone can get access to the code is sufficient. However, as more people join the project—new users, developers, documentarians, etc.—you will likely find yourself answering the same basic questions repeatedly. (And in the process you’ll discover that many aspects of the projects are not as obvious to newcomers as they are to you.) These repeat questions represent opportunities to improve your documentation and to seek help from your community.

Keep your FAQ updated and easy to locate. But even better: ask community participants to help you improve it. When answering a question for a newcomer, be it via email on the project mailing list or in real-time chat, ask the newcomer to write up the question and answer for inclusion in the project FAQ. By asking for help from your community, you do several things:

Ideally, newcomers would have the ability to edit the FAQ themselves. Sending instructions for how to edit the FAQ along with your request to contribute to it—thus lowering the barrier to entry—makes receiving a contribution more likely. If your project maintains a contributors list, make sure to include the people contributing to your FAQ in it. People love seeing their work and contributions (however small) acknowledged. Doing so gives contributors a sense of belonging and commitment to the project. People who feel their work is appreciated and respected are more likely to stick around and contribute to the project, whether by filing issues or adding new features.

Your project’s website should also make clear the purpose of the project and the activities the project has as its focus. People have difficulty understanding how they can best fit into a community and how they can contribute if they do not understand what activities are currently in progress and what is planned for the future.

One common tool to communicate these goals is a project roadmap. Even if your project does not yet have sufficient resources to develop this kind of roadmap, you should still find some way to ensure users and would-be contributors understand the project landscape. For instance, a weekly recap of project activities and planned activities for the coming week or month is an excellent start, and it’s something you can offer through a quick blog or forum post. Such works are an excellent resource for newcomers orienting themselves to the project and are a wonderful place to point interested parties to learn more as part of their onboarding process.

Communicating your project’s non-goals is equally important. Due to the vibrant nature of open source projects, it is only natural that someone will find a use for a project that the project’s creators never intended and will wish to extend the project’s capabilities to target that specific use case. If the project maintainers do not intend for the project to have a wider focus than what is already offered, letting these would-be contributors know this in advance will save everyone time and disappointment. In this era of easy forking, it is relatively easy for those who would use some parts of the project but not others to develop and maintain a code base that better matches their own needs—all without asking the maintainers of the original project to deviate from their intended vision and the project scope they’ve set.

Documenting non-goals is also particularly important for commercially focused projects, where a contributor’s desire to create a feature as open source may be in conflict with vendor goals for creating proprietary features. Contributors may still choose to create that feature as open source, but they should know from the start that upstream maintainers do not intend to include their work as part of the project’s code base. Some may choose to not implement the feature, knowing that a vendor is creating it for them; still others may choose not to implement the feature if they know it will not be included in the project’s mainline source tree, as they do not wish to incur the burden of ongoing maintenance themselves. And others may choose to go ahead and create something that works well for them and release it as open source, regardless of whether the feature is incorporated into the project’s main source repositories.

Most important here is that no one feels surprised by the direction a project will take. No project needs to accept every contribution, but having contributors invest time and energy into developing something only to discover it will not be accepted due to a conflict with an unknown roadmap (commercial or otherwise) creates tension in the community and a lack of trust in the project maintainers. It can even encourage adoption of open source alternatives to the vendor’s product.

An issue tracker (sometimes also known as a bug tracker, issues list, or issue queue) is a tool that allows people to submit reports when they encounter instances where they believe the software is not working as intended.^[5] As a way to monitor pending tasks and allow for collaborative commenting and review of work in progress, some projects manage their entire development workflow via their issue trackers.

In this section, we’ll discuss using an issue tracker for the purpose of reporting failures with the software. By reporting your issue using a project’s issue tracker, you ensure maintainers who are looking out for problems see your report and act upon it.

While filing an issue may seem more cumbersome than simply asking for help in real-time chat, it is important to do for several reasons:

Project contributors cannot keep track of all conversations occurring across various platforms, but they can always refer to the issue tracker to improve the project.

Real-time chat and social media are ephemeral communication channels. The issue tracker is a purpose built tool for recording and reviewing problems with the software. Software projects often define their upcoming work plans by using their issue tracker as a key component—and perhaps their sole tool—to prioritize all possible areas to work on. (Simply put, the project’s issue tracker is very often synonymous with the project’s to-do list.) If your problem does not make its way into the issue tracker, it will likely not be addressed simply because a very busy person has forgotten the details of the problem. For this reason, you will often find that one of the first requests you receive when asking for help is to file an issue so the project maintainers can keep track of the problem.

Filing an issue allows you and the project contributors to communicate asynchronously about the problem, as all parties can refer back to and access the issue description and follow up comments at any time.

When you’ve uncovered a problem with the software, you might discover that the problem is actually the root cause of another problem, or there may be a way in which several problems are related. Issue tracking software allows project developers to group related issues together, which may aid in diagnosing a problem’s root cause.

People often encounter the same issues with software, and many of them are filing issues with the project. Having multiple reports of the same problem can be very time consuming for the project maintainers, as they then need to respond to each individual reporter about work in progress. Fortunately, issue trackers make this process easier for maintainers by allowing them to quickly close issues by stating they are duplicates of an existing one (and then asking the bug reporter to track work-in-progress in the "original" report).

Project maintainers can then engage in broadcast-style communication to everyone experiencing the problem in one place, streamling their workflow while still helping everyone who needs assistance.

Make sure the location of your project’s issue tracker is prominently displayed in your FAQ, as well as in your usage and development documentation. If people cannot figure out where to submit an issue, they will ask someone in the project where to do so. Supporting well-meaning users by offering repeated answers to basic questions like this one can be quite time consuming.

Do yourself and your community a favor and make your issue tracker very easy to find.

Not everyone who uses your software will be familiar with your community’s conventions for filing a useful bug report. To save you and the bug reporter time, offer an issue template to ensure you receive the information you need to reproduce the reported error and effectively triage it. For example, you may need to know what version of the software or what operating system was in use when an error occurred. If common information is required for reproducing errors, ask for it in an issue template.

Common fields in issue templates include a summary of the issue, steps to reproduce it, the actual behavior the user observes, the intended behavior for the software, and a request for log files or screenshots to help guide the issue reviewer in better understanding the bug report. Several issue trackers support templates for bug reports, including GitHub, GitLab, Redmine, and Trac.

If you find yourself asking for the same information over and over again in response to different bug reports, then congratulations. You have uncovered an area of your template in need of improvement.

Most modern issue trackers allow users to label issues they file, which can be useful for organizing project work. By differentiating between different types of requests—features for development, software errors, etc.—a project’s maintainers can be more organized and triage issues more efficiently. Further, many people interested in contributing to open source software projects are looking for issues on which they can work to better understand the project’s development mechanics. If you will actively use labels in your issue tracker, make sure to document the label definitions in your development documentation so those labels are used consistently (or restrict the addition of issue labels to project maintainers only). A list of labels used inconsistently is no more helpful than a list of undifferentiated issues.

Labeling issues as "for newcomers" or "help wanted" allows project maintainers to flag issues particularly suited to contributors who have just joined the project. Labeling issues in this way shows that the project is prepared to onboard new contributors and that maintainers welcome community assistance in a particular area. Don’t be afraid to file issues against project documentation, the website,or anything else you feel is amiss. If there’s a place current and potential contributors can help make the project better, file these in your issue tracker with a clear label that shows them they can contribute.

Just make very clear (either in the text of the "help wanted" issue or via a link to other project documentation) how you wish others to engage with the project when working on these types of issues. (The Apache Subversion Issues page is an excellent example of clearly articulating needs to the user community before they file an issue.) It is best to encourage contributors working on these issues to engage with the project maintainers along the way, so their contributions have a higher chance of acceptance into the project. Nothing squelches a contributor’s enthusiasm like showing up with a working solution to the stated problem only to be told their particular implementation will not meet the project’s needs.

Whether you are a user of the project reporting an issue or a project maintainer reviewing a pull request, it is always important to communicate about the issue clearly and kindly. When a tool is not working, the person using it can become frustrated. Likewise, a person developing a project as a hobby is unlikely to respond well to demands on their time to fix a problem they do not have. Remember to be gracious and thankful in your discussions with other project participants, as everyone sharing their knowledge is contributing to the project’s overall health and wellbeing.

At times, the details of addressing a particular issue can cause tension or arguments within the community.

While healthy and respectful debate is part of any thriving project—software or otherwise—tempers can flare easily, and (as has been well documented)^[6] people tend to behave with less civility online than they would in person.

If an issue has become especially contentious and discourse has become rude or inflammatory, restrict access to that issue for a stated period of time (say 24 to 48 hours) to allow people time to calm down, reflect, and state their argument in a more even-tempered and constructive manner.

Thank the people creating the software for their time and energy, especially if you are new to the project. The individuals spending their (spare) time creating free and open source software for you to use are also people who want to know their time is valued and their work appreciated.

Include as much information as you possibly can about the error you have encountered. If the project uses issue templates, fill one out as completely as possible.

If you do not have the information requested or cannot determine how to get it yourself, simply note what you have attempted to do in order to get the information. These details help maintainers determine what they might need to do to assist you.

If a project does not use issue templates, look at other issues that have been "closed‒fixed" or at merged pull requests to see how other people have filed bug reports. If the issue was fixed, chances are quite good that you’ll be able to use these historical artifacts as examples of the sort of information necessary for reproducing an error. Replicate what you find in these reports and add more detail as you are able.

Thank the submitter for filing the issue. Helping a project improve is an excellent contribution to that project’s health. Further, by being gracious, kind and welcoming, you encourage continued participation and contribution from the issue reporter.

When closing an issue as "won’t fix," explain why the issue will not be fixed. Maintainers shouldn’t feel compelled to accept every pull request or fix every reported issue, but they should at least let bug reporters know why they won’t be addressing certain issues.

In particular, if someone has submitted an issue along with code to fix a problem or implement a new feature, it is vital to tell them why their work has not been accepted by the project. Not doing so makes the contributor feel like they’ve wasted their time and should devote their energies to a different software project. In an ideal world, you are able to include a link to a published project roadmap that explains why the submission does not meet the needs of the project. (Refer to above.)

For new contributor submissions, fix minor issues with the patch yourself along with a note about what you fixed and why. Having a patch rejected for minor nits discourages additional contribution, and often it takes just as long to explain why a patch is being rejected as it does to make very small fixes. Such explanations are an excellent time to point contributors to additional project resources, such as your coding style guide, documentation on communication norms, etc.

For submissions coming in response to a "help wanted" issue, engage early and often with the person who has stated an interest in working on the issue. Doing so ensures that the contributor’s submission will actually meet the project’s needs. Further, by being available to and in regular dialogue with new contributors, you form a relationship with them that encourages mutual learning and increases the chances they will continue to contribute to the project’s ongoing work.

Conventional wisdom in the early days of open source software development held that communities should not carry on development related discussions in the project’s issue tracker. Project communities instead preferred carrying on such conversations via mailing lists or in forums for a number of reasons:

With the rise in popularity of GitHub as a one-stop platform for online development work, conversations in the project issue tracker have become mainstream. GitHub’s issue system visually mirrors the typically expected visual interface for forum software, making discussions in its system seem natural for those who began their development careers when online forums were first gaining popularity. Further, time and resources necessary for maintaining a Mailman instance or additional forum software as part of project infrastructure became cumbersome when all other infrastructure could be managed via a single tool. The addition of features such as the ability to "+1" an issue, set fine-grained controls on notifications for specific issues, and lock specific issues so that only project maintainers may edit it (while still allowing others to view the issue) made the move to discussions in the issue tracker more palatable and effective.

Nonetheless, interested parties should be able to follow discussions outside the project’s issue tracker. Only the most deeply interested and invested individuals will rigorously follow every issue update, making engaging with the project difficult for casual contributors. While excellent search capabilities in online issue trackers make finding closed issues easier, the flow of an issue discussion does not fulfill the same function as a narrative description of a particular implementation or an explanation of why a certain decision was made. Note, too, that some maintainers who are most intimately familiar with the project—those who can recall specific issue numbers for particular discussions with ease—will not always be available to help with the project work.

Preserving the knowledge about decisions in an easy-to-access way:

For example, you may summarize the discussion of the issue in a blog, forum post, or project newsletter, thereby preserving cultural lore for the project while simultaneously informing the broader community about the change. If the project does not maintain a blog or other publication mechanism suitable for such a communication, consider adding a list of watershed issues to your project documentation so newcomers can quickly become familiar with these critical topics, and for ease of reference for long-time project participants.

Though we live in a world where more than 6,500 languages are spoken, for historical reasons the primary language used for communicating on the Internet—and therefore, in major open source projects—is English. For users and contributors who are not native English speakers, this fact can raise significant barriers to participation. There are a few steps projects can take to help those for whom English is not their first language to more effectively participate in the project.

Should your project be widely adopted and grow to the point that it hosts communication channels in more than one language, make sure to list these resources prominently on your project’s website. Include on the project’s website a note that the project welcomes submissions from community members for resources that are not written in English. When the project receives such submissions act promptly to get them included in your project documentation.

As you would with any resource you point your community to, do your best to ensure the resource is helpful. If you are unable to vet the resources as helpful given currently available person-hours on the project, reference the fact that project maintainers have been unable to assess the resource themselves. Note you welcome feedback on its inclusion in the project’s documentation.

As this chapter has stressed numerous times, kind and gracious communication with all those who participate in your project should be a default mode of behavior for interactions. The same holds true when communicating with people for whom writing in English is difficult. If you have trouble understanding what someone is saying or asking for, ask clarifying questions to let them know you will be happy to help them. Don’t simply ignore someone or tell them they are not welcome in the project due to limited proficiency in written English.

Every language features various phrases the actual words of which do not convey the intended meaning of the phrase, such as "over the moon" to mean extremely happy or excited or "raining cats and dogs" to refer to a serious downpour of rain. For those who grow up in a particular culture, the meanings of these phrases are obvious. But they can be confusing for those who lack the proper context for them. Rather than rely on idiomatic phrases, use plain language in written documentation to ensure the writing is most accessible to all people.

While acronyms are a useful way for those completely familiar with a topic to save time and effort typing and speaking longer phrases, they obfuscate information for those less familiar with the topic. Further, acronyms are often overloaded, meaning that the acronym can expand several different ways depending upon the topic area. For example, someone completely new to a project may not understand that "LGTM" means "looks good to me" and that their work is therefore acceptable for merging into the project’s source repository. If you regularly use particular acronyms as part of communicating in your project, take the time to create a quick glossary of these terms. Updating this glossary is a quick and easy way for volunteers to contribute.

As mentioned earlier in this chapter, project maintainers should always be clear about what kind of help they’re seeking from their communities. One key area in which to ask for help is the localization of documentation resources. Regardless of their skill level with software development practices, community members can actively grow the project and improve it by translating documentation, thereby making the project more accessible to more people and more potential contributors. Maintainers should be explicit about their desire to recruit contributors focused on localization.

As has been discussed throughout this chapter, maintaining kind and gracious communications is vital for the project’s ongoing health and well-being. While assuming everyone understands what "kind and gracious communication" looks like may seem natural, one cannot assume a consistent meaning for all participants, especially when dealing with a global audience. Project maintainers and community members do well to lead by example. But it sets an appropriate tone for the project to make an explicit statement about what constitutes civil discourse, what matters are off-topic for the project, and what is expected from anyone communicating with the project, especially about matters that may cause conflict .

From the Diversity Statement of the Dreamwidth Project:^^[8]^

This excerpt from the Diversity Statement of the Dreamwidth project is an excellent example of how to document project communication norms. It is clear that everyone is welcome in the project, regardless of personal background, technical skill level, or focus for using the project. It makes it clear that mistakes will be made and that people are expected to use these imperfections as learning opportunities, not excuses to belittle other people. The statement tells users and would-be contributors that they may not always get what they want from the project maintainers, but that errors will be fixed and reasonable requests will be listened to, if not acted upon. Most notably, it’s a list of expected prosocial behaviors rather than simply a list of what not to do. It identifies behavior the project maintainers and community members model and transforms it from the actions they take into words that help everyone understand what actions constitute good project citizenship.

As projects document their community communication norms, they may find developing a project social contract to be a particularly effective exercise. A project social contract documents behaviors the project expects all participants to display and sets expectations for how project members will be accountable to others. The social contract is not necessarily a list of forbidden behaviors, but rather a statement about how members of the project will choose to self-govern for everyone’s success. By undertaking the process of creating a social contract through dialogue, members establish empathy with one another and set the foundation for future conversations.

You can learn more about creating social contracts, including tips for doing so for remote teams, in The Open Practice Library.

Some projects use a code of conduct as a means to document their expectations around civil discourse. Open source projects that seek any outside contribution should always have a code of conduct. For projects that host events, whether virtual or in person, developing code of conduct specific language around events is also a best practice. Think of the code of conduct as an aspect of the project’s social contract, one that includes the rules by which the community will govern itself and how each member will hold one another accountable for those moments when they could have behaved differently and achieved a better outcome. These rules must be understood and made explicit. Otherwise people will know neither what is expected of them nor whether the project is a place where they will feel welcome and comfortable contributing their time and expertise.

Refer to this guidebook’s chapter on governance for more information about codes of conduct.

Globally, women continue to earn less than White men for performing the same professional roles. They are also increasingly likely to be their homes' primary earners, and they’re more likely to do unpaid labor in the form of housework, childcare, and other domestic tasks.

As a result, they have less spare time to do even more unpaid work by contributing to open source communities. When they do make those contributions, they often do so during work hours—because they already work for organizations that let them do it.

Nisha Kumar (She/They) is the technical lead for container build, packaging, and distribution at the Open Source Technology Center at VMware. She also serves as co-maintainer for the Tern project, and a contributor to the SPDX and OCI communities. She juggles these projects with her role as her child’s primary caregiver. To Kumar, these dual roles are nothing new; as a girl growing up in India, she balanced schoolwork with chores, running errands, and caring for family members. These endless tasks left no time for her to pursue passion projects.

If not for her ability to work on open source during the day at VMware, she’s unsure if she could contribute today. Kumar told me:

The internet is not an equally hospitable place. Women, people of color, and LBGTQ+ people are disproportionately targeted for online harassment, with women twice as likely to experience online sexual harassment as men. And this was prior to 2020.

The year’s confluence of a global pandemic and mass civil unrest has led to increased attacks against people of color, specifically Asian Americans and Black Americans. If attackers feel emboldened to hurt people in the flesh, it’s no surprise that this occurs online as well. If you work on open source projects with Black and Asian contributors, make no mistake: They are in pain.

"I don’t see any acknowledgement that the internet, in general, is mostly inhabited by white men who are hostile to women and URMs," Kumar says. "How would anyone expect folks who are in general harassed on the internet to suddenly trust an open source community to not behave the same way toward them, despite what its Code of Conduct document says?"

Kumar’s concerns are well-founded. Open source communities don’t have a reputation for making most feel welcome. For years, project maintainers have written calls for help, saying they "feel drained, unappreciated, and even abused" on their worst days. A 2017 survey of 6,000 GitHub contributors found that 21% left projects they were working on after experiencing negative behavior. With the odds of such behavior that much higher for people from underrepresented groups, it’s surprising they contribute to open source projects at all.

"Any time that I spend contributing to [open source communities] is time I could also be spending volunteering to advance LGBTQ equality, fighting against police brutality, and other issues that I care about, and that disproportionately affect underrepresented people—in fact, it’s what makes us underrepresented in the first place," explains Perry Eising (He/They), who works as a community manager at a for-profit tech company that hosts open source projects. "It’s challenging to justify to myself to spend time being involved in (sometimes hostile-feeling) OS and tech debates when I have so many causes that require my attention and efforts."

The barriers above manifest in perhaps the biggest barrier of all: Open source projects' lack of documentation. Quantitative data and qualitative interviews repeatedly share that most open source projects don’t prioritize or reward documentation. As a result, outsiders often have no clue how to help.

I speak from personal experience here. After speaking at the Open Source Summit in Vancouver two years ago, I found the community so warm and welcoming that I resolved to find a project with which I could help. Given my background as a writer of all stripes, I thought writing documentation would be the perfect place to start and make a meaningful impact. So you can imagine how my face fell when I created my first GitHub account, logged onto the platform, and was left totally lost by where to go next. With no knowledge of how to fork, merge branches, or make pull requests, I had no clue where to start—and knew the margin for error was high.

I’m fortunate to live in a city with an active tech community that hosts regular meetups for techies of all interests, including tutorials aimed at beginners. I made my first pull request in person at a conference, and then made most of my first several dozen GitHub contributions at in-person events. Only after attending several free, accessible events over several months did I begin contributing independently. Absent any of these privileges, I would not have spent hours alone trying to learn how GitHub works to make a PR that might—or might not—get accepted.

The same GitHub survey that found one in five open source contributors leave projects due to bad behavior also found that incomplete or confusing documentation was the biggest challenge. 93% of that survey’s respondents said they had encountered the problem, yet 60% said they rarely or never contributed to documentation. As a result, it’s hard for project veterans to read their own projects' documentation.

Imagine how this makes outsiders feel.

"Contributing to open source is not only a technical challenge but equally a social challenge," explains Nuritzi Sanchez (She/Her), a senior open source program manager at GitLab. "Documentation is needed to enable remote asynchronous collaboration, which is how communities work. If everything is stuck inside of people’s heads, that’s going to create an atmosphere of confusion, frustration, and inefficiency." Documentation isn’t just essential for code; it’s also a guide to understanding each project’s cultural and communication norms (refer to this guidebook’s chapter on communication norms for more on this subject).

Open source communities use asynchronous communication to work cohesively across disparate time zones. Without clear documentation, prospective contributors won’t know how decisions are made, where to contribute to the project, how teams collaborate, or why following certain processes is important. For prospective contributors who are non-native English speakers and/or have special needs, this lack of documentation makes contributing all but impossible. Inadequate documentation has far-reaching consequences. It shows a lack of transparency that wastes time, sows distrust, and prevents many open source communities from reaching their full potential.

The first step to a more inclusive open source project involves understanding the meritocracy myth: The more you believe in meritocracy, the more biased your project is likely to be.

Why? Purely meritocratic projects don’t acknowledge that people enter on unequal playing fields. If an open source maintainer isn’t aware that women often have less time to contribute, or that LGBTQ+ contributors are more likely to endure online abuse, they won’t take steps to make the community more inclusive. As a result, they risk losing the diverse contributors they worked hard to recruit.

Terri Oda (She/Her) volunteers for the Python Software Foundation and Google’s Summer of Code, alongside her role as an open source security researcher at Intel. She says claims of meritocracy make her cringe. Why? Such statements cause maintainers to ignore opportunities to get more people involved in projects, even in cases where the open source community gathers in person.

"For example, say you’re running code sprints at a conference and want to increase the number of women," Oda says. "If you’re thinking about merit and skills, you’re going to wind up offering more intro to sprinting-type content. But if you look at the bigger picture, you might realize that the conference offers childcare during the main conference, but it stops when sprints start. Or that the venue isn’t in a safe area and the sprints run until after dark."

The first step to build a more inclusive environment is self-awareness. Open source contributors enter projects with a range of lived experiences that affect how—and if—they show up. Sitting with and reflecting on this fact is the first, most crucial step.

The next step is to take an honest look at your project’s current community, and take note of who is—and isn’t—there. If your project contributors all, or even mostly, look like you, that’s a huge red flag that an inclusive overhaul is in order.

A 2019 Stack Overflow study found that about 41% of developers have less than five years of experience. Between these new technologists and current emphasis on STEM education, there are lots of opportunities to welcome new open source contributors. In order to do so, project maintainers must lower barriers to entry—and clear, concise documentation is the first step.

Zach Corleissen (He/They) is the lead technical writer for The Linux Foundation (LF) who recently revised a large architectural document for the LF Energy Foundation. He also serves as one of the co-chairs for the Kubernetes documentation special interest group (SIG Docs). Kubernetes was his first open source software project, and it quickly became one of the most prolific projects in modern open source. Its rapid growth allowed Corleissen to own important aspects of its documentation, and revise it to become more reader-friendly.

"Insisting that code is self-documenting is a form of gatekeeping [and] an example of an unhealthy project culture," Corleissen says. "I think the devaluation often comes from developers who see a static generator stack and think, 'How hard can it be?' One of my least favorite dismissive phrases: 'It’s just a pile of Markdown.' If only it were that easy! Documentation is code for an environment where no chipsets are identical; kernel defaults are hostile; RAM is variable; storage is subject to random external dependencies; and production regularly fails despite optimal conditions, or inversely, succeeds in spite of obvious CI failures."

To track progress, the SIG Docs group does a quarterly review where they measure the progress of their previous quarter’s goals and prioritize work for the upcoming quarter. One of their community rules centers on ownership: In order to adopt a goal, a project needs a specific person willing to drive it.

If your project doesn’t already have a code of conduct (CoC), it’s never too late to make one (refer to this guidebook’s chapter on governance for tips of getting started). They are an expectation for modern open source initiatives, from long-term projects to two-day conferences.

In my own research for this chapter, several open source contributors told me they won’t consider joining new projects that lack clear CoCs. For these URMs, the risk of joining an unwelcoming if not hostile community is too high. "Having a code of conduct would be big for me," explains Natalie Zamani (She/Her), Senior Software Engineer at Apple. "And then something as seemingly unrelated as not tolerating project contributors espousing racist/sexist/homophobic/transphobic ideas, even if it’s not related to their project work. I wouldn’t feel comfortable working with individuals who hold such views, full stop. And I’ve seen a few projects that would otherwise be interesting to me where that’s tolerated."

As the former President and Chairperson of the Board of Directors for the GNOME Foundation, Sanchez helped create GNOME’s event CoC. She says that while the Contributor’s Covenant is the default code of conduct for a lot of open source communities, translating it to an events format took some creative work—and a lot of feedback from the GNOME community.

"No matter the type of CoC you’re rolling out, having a transparent plan and timeline is key," Sanchez says. "At GNOME, we created a working group after one of our annual conferences to start drafting a code of conduct. We passed the notion of a working group by the Board of Directors to make sure that they were on board. They made a community-wide announcement letting people know the process: A working group would be drafting the CoC, sending it to community for revisions, the Board would then see the revised draft and vote, and then the membership would vote at the Annual General Meeting."

Despite the key role of community feedback, Sanchez says the CoC should be owned by a governing body within your project. CoCs remain a touchy subject in open source communities, and not all open source contributors believe they’re necessary. A governing body (or at least a committee) composed of diverse contributors that shares the creation process can help alleviate disagreements. Once you’ve created your governing body, assign members to own specific tasks. These include a chair who can break voter ties, moderators to enforce the code of conduct, and mentors to train the community. It’s essential for all community members—especially URMs—to see project leaderships protect their safety and integrity.

"I am a firm believer that signalling is very important, but that broken trust is difficult to repair," Eising explains. "Don’t signal to [underrepresented people] that you are ready to embrace them before you actually are—that’s like inviting someone who uses a wheelchair to a party on [an upper] floor with no elevator. That person won’t trust you again to think about their needs appropriately. Organizations need to look within and really assess before making a reach-out."

In her time working on open source, Sanchez says that most projects focus on attracting contributors to a narrow set of project work: Engineering, design, translation, documentation, and outreach. Despite how broad that sounds, she says the table below reflects many more roles and types of contributions she’d like to see rewarded.

Use this table as part of your outreach efforts, focusing on specific career areas and development goals. Help people to see themselves as part of the project, showing how their skills and experiences in a career area can map to where they can contribute to the project.

This list isn’t exhaustive, nor is it applicable to all projects. For more on this topic, refer to this guidebook’s chapter on the range of roles in open source projects. The goal is to look at your own open source project’s holistic needs in the short and long terms, then recruit contributors to fill specific gaps. Doing so allows you to create a governing board with representatives that own specific aspects of the project and contribute to its growth.

Nithya Ruff (She/Her) leads the Open Source Program Office for Comcast and serves as Chair of The Linux Foundation Board. In more than two decades of open source work, she has seen how ignoring crucial skills—including legal issues such as copyrights and trademarks—can keep a project from achieving long-term success. Recruiting and rewarding diverse contributions also plays a key role in preventing burnout, which project maintainers have been increasingly vocal about.

"It is unfair to expect the maintainer or the developer who started the project or leads the project to care for all of these issues, [or] have the skills to do it," Ruff says. "All forms of contribution need to be valued [because this] brings diversity of people into the project, which makes the project more vibrant and innovative. Foundations like the Apache Software Foundation [and] Linux Foundation bring all of these contributions to the table for their hosted projects. This allows the project to more successfully build a broader ecosystem."

Eleven years after co-founding Redis, Salvatore Sanfilippo announced plans to step down as Project Maintainer of the NoSQL database. He named Yossi Gottlieb and Oran Agra as his successors to maintain the Redis project. In doing so, the Redis governance model got a refresh.

Rather than keeping Redis’s prior BDFL style, Gottlieb and Agra built a new, lighter governance model. It involves electing a small group of longtime Redis developers to act as core contributors and uphold the project’s Code of Conduct.

Regardless of your own project’s governance model, you must include a way to train key contributors to assume leadership roles. This achieves three key goals:

This last point is noteworthy: Sanfilippo said when he stepped down from Redis that despite his passion for coding, he never aspired to maintain a project. Without new leaders to step up—and documentation sharing how contributors can assume such roles—maintainers risk either working on projects when they no longer want to or having the project stall. Likewise, the project risks missing an opportunity to give interested contributors a chance to step up.

The act of building and maintaining a mentorship program is inclusive in itself. Several open source leaders interviewed for this book said they see a clear need for more mentorship in open source at large, and a desire to do it themselves. In some cases, open source contributors believe so much in the power of mentorship that they restructured their contributions to include it. And, because they were mindful of their own time limitations, they offered flexibility to new leaders as well.

"My open source contributions definitely changed even before I became a parent," explains Oda. "As the coordinator for a global mentoring program that happens in the summer, I had to plan some years ahead to build a volunteer team that could do everything I do. So, I handed off some of my other projects more completely and never went back to them.

"Since new moms typically get less than one hour of free time per day, the key for me has been aligning the open source I want to do with the open source that work wanted to pay me for. I worked to take [the] CVE Binary Tool open source after I returned from maternity leave, and worked with my boss to make sure I could have time to mentor students as part of my maintainer role."

To build your own mentorship program, Sanchez says to focus on four actions and initiatives:

For more ideas around mentoring in open source communities, refer to this guidebook’s chapter on building a culture of mentorship.

The work of inclusion is never done: It’s ongoing. As your project grows, you will find new gaps to fill, questions to document, and additions to your Code of Conduct. As your community becomes more inclusive, it might feel like you’re finding more ways you’ve fallen short. Uncomfortable as this is, it’s actually a good thing. It means you’ve done the hard work of committing to keep on getting better. And, if you’ve done the work of building an inclusive team, you won’t do this work alone. Instead, you’ll share the work with your community, giving everyone the chance to share their feedback.

To keep the dialogue ongoing and open, give your community options to leave feedback on their experiences. This can range from quarterly surveys to giving contributors the freedom to create channels in your project’s communication platforms to chat about mental health, being a person of color, how to handle negotiations, etc. Such channels give contributors ways to connect socially, which is crucial for increasing asynchronous collaboration. It also gives you new ways to support contributors so they can contribute more fully.

"I am hearing-impaired, and I requested that the All Things Open conference consider [hearing impairment] when in larger venues where keynotes were speaking and there were no specific adaptations [in the venue] for those of us who were not able to hear," explains Don Watkins (He/Him), a community correspondent for OpenSource.com who has been active in the Linux community for two decades. "Specific adaptations were added [by All Things Open] for those us were not able to hear."

"I was particularly impressed when attending the Creative Commons Global Summit in Toronto in 2018, where nearly all presentations were accompanied by folks who signed and also provided simultaneous closed captioning of all speakers."

Inclusion isn’t a one-time pull request: It’s an ongoing, important activity. Without building and sustaining inclusive communities, there’s no hope of improving diversity of open source contributors. To recruit new talent, prevent maintainer burnout, and create affirming online environments, open source maintainers should commit to inclusion. Change starts from within, and when technology contributors from a variety of backgrounds see your inclusive efforts, they will be much more likely to join.

"Make it easy for people to get involved and to contribute back," says Ruff. "The mark of a good project is not how complex it is, but how easy it is to get involved."

Traditionally, university engineering courses do not put a strong focus on clear written communications. This can lead to professional software developers who have not developed their writing skills. In open source projects, written communication is critical to working asynchronously with a community team: blogging to promote work, documenting feature proposals, or debating the pros and cons of roadmap items on a mailing list.

In addition, while most engineers appreciate good logic, rhetoric and debate are not typically part of an engineering syllabus. The end result is that when asked to write about their work, or to ask a question on a public forum, they hesitate.

For non-English speakers, lack of confidence in English proficiency can also be an issue that gets in the way of mailing list participation.

I remember one engineer I worked with, who was very hesitant to write email about topics we discussed, even when we agreed that they needed to be discussed with the community. When he did, he appeared to ignore responses or questions from community members. When this was discussed with him, it was clear that he did not feel comfortable engaging in a discussion in writing on a publicly archived mailing list. He was nervous that any mis-steps or breaches of etiquette would be dealt with harshly by the community.

The best way to cure this problem is with baby steps.

A great first step is to get engineers answering questions. One way to help is to publicly refer a question to an engineer on the mailing list, while affirming their expertise in the area. "Tammy knows the RLE algorithms inside out. Tammy, would you mind answering Franz’s question, please?"

This is something of a Jedi mind trick, and serves three purposes. First, an individual can easily ignore a question if it is addressed to a group, but it is a rare person who doesn’t answer when you ask them a question directly–it’s human nature.

Second, affirming your engineer’s skills reinforces that they are indeed seen as the expert in the area in question, giving them more confidence to answer. Third, by identifying an individual engineer with a specific skill set, you are giving people outside your company a glimpse inside the walls. You are making your team human, a collection of individuals with different strengths and weaknesses, rather than an amorphous group—"the Acme Co developers."

Another worthwhile thing to do is to get developers into the habit of writing regularly. It is not enough to stand over people and ask them all to have a blog. If writing is intimidating, then doing it more often will make it less so. There are many ways to do this–rewarding blog posts, requiring regular status reports, longer commit messages or comments when closing tickets, or scheduling time for creative writing workshops. The goal is not to turn developers into novelists. The goal is to get your team in the habit of writing.

Finally, you should train your engineers in basic netiquette and writing good emails. Developers should treat writing email in a similar way to patches. When you generate a patch, typically the last thing you do before you send it is you check over it, to make sure nothing silly is included. The same habit applied to email would identify any places where phrasing is awkward and ambiguous, resulting in better email.

While writing can be intimidating for many software engineers, subjecting their work to peer review to a group of people they do not know very well can be nerve-wracking.

In my experience, systematic peer review is not the norm in the software industry. Some managers see peer review as overhead. After all, the developer was hired because they were competent to do the job, and nobody likes to be second-guessed by "the community." Once engineers reach a certain level of experience, peer review seems to be more an exception than the rule for professional software developers in our industry.

In community projects, peer review is expected. In fact, it is a best practice, one of the things that separates successful community projects from the crowd. Community developers expect to hear about features before they are developed, and have an opportunity to suggest better ways the feature can be implemented. They expect new contributors to submit patches that they can review–it is the way a new contributor builds trust before gaining committer or maintainer status.

The best way to get people used to peer review inside professional software teams is to have a company policy against the "day one commit bit"—the practice of getting commit access to an open source project repository on the day you start in the company. For corporate-sponsored projects, new developers should go through the same review process for their work that contributors outside your company have to go through.

For corporate contributions to community projects, that means discouraging internal branches and a "gatekeeper" project structure, where one or two developers commit the work of others in the team.

Developers should submit their work upstream at the same time it is being submitted internally. For those changes which only apply to your internal branches, peer review should still occur in a private repository. With the recent advent of git-based repositories as a norm for software development, this is less of a challenge for companies now than it once was, and it is necessary to transition your team to successful community contributors.

Having new developers go through this review period is important for a number of reasons–the most important is that you are demonstrating that employees have the same burden to prove themselves in the project as non-employee contributors, and it provides new employees with a period where they familiarise themselves with project coding and communication conventions and norms, and when they also introduce themselves to the community at large. This is fundamental to the mentorship of new developers by more experienced community developers.

In the mind of some developers, posting project plans to the mailing list constitutes an announcement and needs substantial preparation. These developers frame communicating with community users on a mailing list as being equivalent to "support" or "communication," and not as a core part of the engineering function.

If a developer frames "sending an email to a mailing list" as "making an announcement," it fits in the "marketing" box in their head. A developer once told me she didn’t have time to send email to the mailing list, because she had real work to do. "Dealing with the community" was my job as community manager, as far as she was concerned. In her mind, community messaging was a type of support, and was not part of her job.

The authors of The Cluetrain Manifesto claimed that in the modern connected world, there is no such thing as a marketing department, that every interaction between an employee of your company and someone outside your company is an opportunity to win or lose reputation.

In free software development teams, this is even more true. There is no marketing department for project communications. To be productive, you need to talk to your peers, so the institutional barrier to external communications must disappear for people dealing in community projects.

Even in organizations that are clear about their expectations for open source communication, engineers may impose limits on themselves. They might spend hours polishing proposals before sending them on. This is counter-productive in community projects, since the more polished an initial proposal is, the more emotional investment has been made in it. Polished proposals are harder to review and change, too, since they look done already. It is better to release a rough early draft, giving the author an opportunity to integrate early feedback.

The best way to prove to your team the benefits of "release early, release often" is by example. As a team lead or manager, you can lead by publishing team plans publicly and early, and iterating often. When you do, point out the benefits which result to your team. Breaking down this barrier will take time, but by making it clear that perfection is not expected, and by rewarding early release of information and encouraging feedback, your team will soon learn that participants outside your company are peers, not an audience.

Another useful technique is to ask your engineers to break tasks into smaller parts, so that even if they do hold off until the first part is up to a high standard, information is still getting out there more quickly, allowing feedback to inform later stages of the process.

Working against the goal of early communication is the common desire for the big reveal. Companies often want to align product releases and announcements with major trade shows. This can lead companies to ask their engineers to work internally on significant features for fear that the big surprise will be ruined otherwise. The alternative seems to be to announce a project when you start, rather than when you have something to show–but this can result in a long wait before products get to market, and impatience and bad press from the mainstream press.

It is possible to separate engineers discussing design decisions and implementation details of significant features in a mailing list, and using a press release and marketing campaign to promote an announcement. When the final announcement comes out, the community will not be completely surprised, and you will not find yourself having to defend yourself for working in secret for months, and proposing a big code drop which is difficult to review.

The key lesson here is that you want your developers to feel a connection to people working outside the company. That requires people outside your company to feel a connection with them, too. By drawing the curtain back on your team, its members and their skills and priorities, you are creating the circumstances for the people working on your project to come to appreciate each other as peers, and to feel comfortable discussing features and patches on their merits.

When you get to that point, you have won the battle. Developers in your team will see other developers working on the project as peers, colleagues, and even friends.

An effective community requires more than simply opening the door and waiting for people to join. Leaders must look at the skills and knowledge the project needs, and research who can provide these.

To make sure a useful product results from your efforts, representatives of any groups who are potentially affected by the project should be invited to join the project. The affected groups who need representation include potential users, other technical projects that are affected, and people who are under-represented (see the section on Diversity). Leaders of each project must take explicit action to determine who stakeholders are and to engage representatives of those stakeholders.

The principle behind such engagement is that users, and other groups who may be affected indirectly by a project, have needs that are often hidden from outsiders. Bringing in representatives of all affected groups helps the project produce a more useful product that all can enjoy, and that is fair to all. There is a practical motivation for early engagement too: you avoid the risk that someone will denounce your project at a late stage and prevent its adoption.

Onboarding a steering committee member should include:

Open source projects move along best through consensus, but this can’t always be achieved. The simple solution adopted by many early open source projects, where the final decision is made by a single project leader (usually the founder of the project, and sometimes called a benevolent dictator) doesn’t work well over time. That is why the project should form technical and community steering committees to take responsibility.

Voting can be useful to gauge the mood of the community, but is not definitive the way it is in a parliamentary vote. This is because those who join the project and who vote are self-selected. Therefore, the vote may be biased.

See the section "Enforcing norms" for conflicts involving possible violations of the code of conduct.

Leaders should be on the look-out for ways to get members to take on larger volunteer roles. They should put particular effort into people who identify as members of groups that lack representation (as discussed in the section "Diversity"). When a member shows interest or initiative, the leader should encourage it through a conversation. Possible invitations to do more are:

Note that each "ask" includes an estimate of the time involved. But sometimes, the invitation shouldn’t mention a time commitment because it might be big enough to scare away the member. Better to hook them on the important of the task they’re being asked to perform. Then their excitement—​and hopefully a positive experience working with others—​will carry them along.

As with recruitment and other aspects of managing members, development must be done with special and conscious attention to encouraging women and members of other historically excluded groups to flex their muscles in new responsibilities. Never assume that a certain type of person is suited (or not suited) to a particular task.

Volunteers come to a project for many reasons. Experts want to create standards around their practices, students come to hone their skills, and everyone wants to make better technology for the world. But at all levels, people appreciate being rewarded for their work and will contribute more if they feel rewarded.

A badging system gives contributors a clear goal to aim for, and marks people who might be able to contribute at higher levels and move into leadership. See [Badges for individuals and projects]() for more about this concept.

Metrics are crucial to determining the contributors to reward. And these must be meaningful metrics that reflect real achievements; otherwise they can offer perverse incentives to do things like make worthless commits. See the section "Who has contributed".

Getting volunteers to rise into leadership roles is hard. Most joined the project to contribute their technical skills, or other roles as an individual contributor. They tend to be afraid of the time commitment of taking on a leadership role, or see the tasks as boring distractions from what they really love to do.

On top of this, leaders are busy dealing with the needs of the project and have trouble finding time to recruit and mentor new leaders. Yet these tasks are critical to long-term projects.

Recruiting leaders is an aspect of member development. Look for members who are asking deep questions, proposing new directions for the project or new ways of marketing it, or other informal aspects of leadership. You can engage them in two ways: you can describe an open leadership role and ask directly whether they would be willing to step into it, or start a dialog where you find out what they want from the project and then encourage them to take on leadership in order to achieve these goals.

Serving in a leadership position is both a time commitment and a serious responsibility, but it’s a wonderful chance for growth that everyone should do. Here are some possible incentives you can offer people whom you invite to join your leadership:

Don’t stress the time required for the role. Often, the first question a volunteer asks is, "How much time must I spend?" Try to get them to think of the benefits to the project if they become leaders, of the enhanced position they’ll have, and the benefits it will bring them. Don’t be afraid to flatter members by explaining how important they are—​it’s all true!

Healthy projects highlight people’s contributions, because most of them are not being paid to do and have no personal benefit except recognition of their effort. Furthermore, when you know who has contributed the most, you can help people rise in responsibility in a kind of meritocracy.

Luckily, software and other text-based projects provide tools that automatically measure certain types of contributions. Use source control, the bug tracker, and other tools to track a few metrics you think are key. Lines of code are not a good measure of productivity. But numbers of bugs fixed and numbers of changes accepted could be useful.

Is the project actually contributing to its field? Numbers of downloads are one crude but useful measure. Many people download a product to try it out and then discard it, so use other measures if possible to gauge the real growth of the user base: for instance, look at the number of people participating on forums and the number of questions asked.

This helps you know whether the project is making progress. It’s also important to have the right mix of project members: some who have been on the project for a long time and can provide institutional memory, along with more recent recruits who provide new blood. The forums should record when people joined and left, so you can develop metrics from that information.

Another important set of metrics concern how many bugs get fixed, and how quickly. It’s not bad for a project to have a lot of bug reports. Every project has bugs, so a steady stream of bug reports shows that people are using the product. But the bugs should get fixed!

Mentoring can be a personally rewarding experience. The help and guidance you offer can have valuable, lasting benefits. For example:

Mentorship helps contributors navigating different stages of their careers or different life circumstances. Mentorship has the potential for positive impact (big and small, yet valuable just the same), whether it occurs among people in a specific project of initiative, in general as people get started with the project, and as people grow and advance in their educations and careers.

Mentoriship has a cumulative effect on community coherence and identity. It might begin between two people, when one person mentors another. But that person may mentor someone else in turn—and the positive ripple effect continues. It might even become a sort of "boomerang of help" that returns to you when you need a helping hand or some advice.

At scale, it helps contribute towards more inclusive, collaborative, helpful, and innovative communities.

Creating a culture of mentorship—or even a sopecific mentoring program—is important and valuable to the long-term health of an open source project. The rest of this chapter will discuss those benefits specifically.

Even if it’s lightweight, write it down and give it an initial try.

For that first e.g. six months, get a handful of volunteers to try out the program. This gives time to work out the kinks in processes, and to attract more mentors for when you make the program more prominent.

When you have a process you have tried and tested once or twice, put up a "Mentoring" section on your project website and include links to all the elements of your mentoring program. Make sure people who have even the slightest inkling of getting involved in the project can look ahead and see how they are going to be taken care of as a new contributor.

After each full mentoring period (refer to time commitment, below), conduct a retrospective to learn from the mentoring period and improve the process iteratively.

It’s not just promising there will be a map and directions, it is showing the actual map and idea of what the directions will be.

Even people who are very experienced at mentoring benefit from having guidelines for how to mentor and work with mentoring subjects (mentees), mentoring ethics, and so forth.

As a deeper reference when creating a mentoring program, there is an upstream guide to mentoring itself. You can use materials from that project to create the elements your mentoring program needs.

Mentors have a special role of trust—the project trusts them to represent the community, and the mentees (mentoring subjects) trust the mentor to lead them down the right path. Mentors need to conduct themselves with an appropriate standard, and there needs to be a way to keep them accountable to that standard and report problems or abuses of conduct by mentors. Such a Code of Conduct needs to be visible up front and prominent for everyone looking at your mentoring program.

Not having a Code of Conduct for your mentors, or making it hard to find, is a warning signal to potential new contributors that this project should be avoided.

If your project already has a Code of Conduct, make sure it is sufficient to cover the mentoring program, and make sure all participants are aware of its existence.

It’s one thing to have a few mentors and to start a mentoring program. But to make it sustainable, the mentoring program needs to doing more than attracting mentors, it needs to be creating new mentors.

The core idea is to make sure that your mentors are also teaching explicitly and by example "how to be a mentor." Your mentors should be thinking overall and in specific instances, How can I help this person be successful at mentoring other contributors? That way new mentors are made of people who have had positive experiences as mentees and are also encouraged in their own mentoring activities beyond.

A new contributor who is mentored well can immediately turn around and offer similar mentoring lessons to other contributors, new and existing alike. Even the same day.

Whenever you are answering a question for a new contributor, how you answer that question is where mentoring comes in. You can answer in such a way that this new contributor feels empowered to share their new-found knowledge. If they take in the lesson of not just what was conveyed but how it was conveyed, they carry this simple lesson of mentoring forward with their own interactions across the project.

Unlike your mentors, you want the fewest demands and lightest burdens for your mentees.

This is information that should be prominent on your mentoring program webpages, and can cover:

You are looking for a balance where mentees know what is expected of them, while leaving space for the mentor to help grow that understanding of project norms, from technical to cultural.

For everything from people being stuck, through to disappearing mentors, to Code of Conduct violations, there needs to be a clear and obvious person or persons to contact.

This contact information and its purpose should be prominent on your mentoring program webpages.

This group will be one of the rare areas of your project that maintains privacy and a well-understood barrier to transparency for specific topics. Mentors need to be able to talk with other mentors to seek guidance; this group can provide that private space. It can also help with any sensitive matters that arise.

The governance for this group or role needs to have a clear and short escalation path to the highest levels of project leadership.

Mentoring relationships can last years or be completed in a weekend. Make a reasonable schedule, perhaps one that is tied to your release schedule or other rhythms such as specific conferences or events you organize around.

For some projects' experience, the six-month commitment seems to work well. It is enough time to get to know each other, talk through how to help as a mentor/be helped as a mentee, and then some months in the middle for the mentees to actually get feedback on real activities.

Especially if you are starting out, you want to attract mentors. If there is too long of a time and effort commitment, or if there is not clear closure to a round of mentoring, many potential mentors will not join or even inquire further about your program.

Making the time and effort commitment nebulous is like sprinkling mentoring repellant on your project. Be clear on what participants are getting into, and your mentoring program can be on a path to success.

One of the things that is most useful when you are coming into a new role is a list of the people with whom you will be working.

If there are stakeholders who might be able to help you, or people you will work with who have concerns about community goals, this information will enable a new person to come into the role and avoid any pitfalls or faux-pas.

As the outgoing community manager, one of the most valuable things you can do for the new community manager is to introduce them to people who you have worked with, to smooth the transition, and ensure that they don’t have to spend minutes explaining who they are and why they are turning up in places where they are not expected.

A common theme among people who have had bad mentorship experiences is the omnipresent micro-manager. One community manager described an experience where they took on a community role from someone who was stretched too thin. However, everything that they did in the role resulted in email correcting them and telling them how they should have done the task differently. As a result, they drifted away from taking on the role. One question more than any can make a person in a new role feel small and inadequate: "Why didn’t you just…?"

A new person in any role will do things differently than the person who went before. There can be a few reasons for that. Maybe they don’t know how to do it the way it was done in the past. There may be reasons which led to you doing things the way you did, but they’re unaware of the history. It’s also possible that they bring a different skill set and perspective to the role, and their way is just as valid and just as good.

Whatever the reason, avoid asking your mentee "why didn’t you…?"

You have to give the new person in the role the freedom to do things differently. Even if they make mistakes, it is important that they feel ownership over the role.

As a mentor, one of the hardest things is to watch someone struggle to do something which you have done in the past. That does not mean that you should completely abandon your new community manager. Instead of telling them what to do, ensure that you have good documentation for tasks they will need to do in the role, and point them at the documentation.

This gives them guided experience, while showing up any places where documentation is lacking and also giving them the freedom to tweak things along the way.

Ironically for the most public-facing people in a project, people in community roles can see their careers suffer for lack of visibility. More than one person mentioned seeing their careers suffer because their management chain was unaware of the work they were doing, or did not understand its value.

As the experienced community manager, one of the best gifts you can offer a junior community person is being a credible cheerleader for their work.

New community managers can get stretched thin, or can focus their efforts on tasks that do not provide a significant impact on the community.

As a mentor, you have an opportunity to help them channel their efforts on aspects of the role that provide value to the sponsoring company, in addition to benefiting the community.

You may also have the ability to communicate their successes in a way that will help their management chain understand the value that they bring to the project.

Guiding a new community manager through their first few months on the job can be a very rewarding experience. As the experienced person, you can help them be effective and successful, give them confidence in their ability to execute in a new role, and increase the amount of community knowledge in your company and in the industry.

What would the first 30 days of a mentorship program for a new community manager look like? You might try to:

Beyond the first month, you should be fading increasingly into the shadows, moving your one-on-one calls to every two weeks, and providing guidance on-demand only.

If you have done your job well, your mentee will be well on their way to making the job their own.

A great deal of activity hinges on roles-related governance in open source projects. Think of a role as a function someone in the project performs.

When analyzing your own project’s roles-related governance systems, ask the following questions:

While contributors occupy certain roles in an open source project, the project’s governance structure also determines how those people do what they do as part of the project. Policies and procedures refer to the processes and guidelines contributors follow when performing their roles.

When analyzing your project’s procedure- or policy-related governance systems, ask the following questions:

Remember: A project’s roles and its policies and procedures aren’t discrete; they’re interwoven as part of the project’s overall governance model. For example, consider a project role called "Documentation Maintainer." A project might outline that role this way:

In many cases, a project’s actual role descriptions are more elaborate than that (some projects' role handbooks are dozens of pages long). As projects mature, the number of different roles people play in them can increase. Moreover, larger and more mature projects associate roles with collectives—that is, a group of contributors can perform a certain role jointly. For instance, a project might feature several "steering committees," each with its own set of election procedures. This is true for the Kubernetes project, where "special interest groups" are a popular unit of governance. In that project, the role of Code Contributor is subdivided further by interest group (team) and by contributor level (Member, Reviewer, Approver, and Owner). So a contributor’s actual role would be something like "SIG‒Network Approver," not just "Code Contributor."

Projects that start with a single developer (or small group of developers) do not often require any formal governance structure. Gauging consensus is easy, and during the early stages of a project, disagreements about what should be done (and who should do it) are rare. A project’s early members all typically have carte blanche to take the actions they see as best for the project, like approving code for inclusion. Normally, no structure is required in addition to a GitHub repository, and all early developers receive project membership status almost immediately.

As projects begin growing, the limitations of this approach become obvious. When a project has even five developers, coordinating work becomes more difficult, and newer developers may not be immediately familiar with the design choices and coding standards the project’s early developers have followed.

So the first evolution projects tend to undergo is often one that requires code submissions to undergo peer review before being merged. The "first level" of the project’s hierarchy consists of those with the authority to approve pull requests or code and content submissions for inclusion in the project. Initially, deciding who receives this authority is easy; the project’s original, trusted developers all receive it, and the project founder acts as final arbiter in case of disagreements.

The next event to trigger a project governance evolution is often related to how people who join the project become recognized members of the group. This tends to occur when the size of the project has increased to approximately 10 or 15 developers. At this point, a project community typically must develop more formal guidelines for admitting new project members.

One common standard projects use to assess new members is sustained participation (how long and how often the contributor has been active in the project) combined with a judgment about what one might call "good taste"—an assessment about the quality of work a contributor tends to submit, that contributor’s good judgement in review comments, etc. Still, the project founder tends to be the gatekeeper and final arbiter of who gets promoted inside the project.

Initial efforts to increase community engagement in the projects tends to focus on growing adoption and engaging with early users. Pre-existing developer teams typically continue project planning, however, in a centralized manner. For this reason, external contributors may find engaging with the project more difficult—and the project may not gain sufficient traction as a result. The rapid pace of project changes, the opacity of the planning process, and the strength of pre-existing relationships between the project’s developers can make feature development more difficult for external contributors. Early patch submissions may stay unreviewed for longer periods of time, and these submissions will be relatively infrequent.

This is as far as many corporate-originated projects will evolve. While the core team may engage actively with the project’s user base, resources required to grow that developer base are considerable, and many organizations choose not to make the investment.

However, one oft-cited benefit of the open source model is an ability to collaborate with industry partners and competitors and share the burden of development of common requirements. If this is a goal, then growing participation in a corporate-originated project beyond a single vendor is critical.

For corporate-originated projects, expanding project participation involves engaging with both interested individuals who are using the project and vendors who might be motivated to invest in the project. Uniting these parties will have implications for project governance.

Many projects begin enticing other vendors to contribute by demonstrating a viable market for the project. Vendors typically do not invest sustainably in open source projects unless they can justify that investment. Illustrating significant and enthusiastic user adoption of the software is therefore critical at this stage. Initial efforts focus on accelerating adoption momentum and successfully converting users into contributors by soliciting their active participation in the project roadmap and project promotion.

Alternatively, a project may attempt to engage with other vendors by focusing on encouraging collaborators to "build on" a common platform. While companies may not be able to justify significant investment in the project "core," they may be able to justify investment in extensions to a project—if those extensions are relatively inexpensive and can support their business.

For example, by focusing initial outreach and engagement efforts on the APIs, the developer experience for extensions, and the path to distribution for people writing those extensions, projects may grow large communities of vendors building atop a platform, rather than modifying the core platform itself. Distinguishing these two areas of development—between the "core" and the "periphery"—often involves making governance decisions specific to each (only some project roles may receive permission to operate in the project "core," for instance).

When a corporate-originated project has demonstrated substantial market opportunity (either by proving that the project fills a significant gap in the market or by growing a large user base directly), it can engage with potential vendor partners to collaborate on the project. This discussion is partly technical and partly business-focused.

Before making a significant investment of engineering resources in a project, vendors will likely ask:

Accepting participation from additional vendors can significantly impact a project’s governance. One way to ease potentially turbulent impacts is to target vendors with whom the originating vendor does not compete directly. For example, a cloud hosting company may have more success recruiting a vendor of on-premise software products to its project than it would recruiting a competing hosting vendor. Competing vendors may only be willing to join when a project can demonstrate a consistent record of multi-vendor engagement in the project.

Open source projects adopting the "do-ocracy" governance model tend to forgo formal and elaborate governance conventions and instead insist that "decisions are made by those who do the work." In other words: In a do-ocracy, members gain authority by making the most consistent contributions. Peer review remains common under this model; however, individual contributors tend to retain de facto decision-making power over project components on which they’ve worked most closely.

For this reason, some do-ocracies will claim to have "no governance at all," relying instead on individual stakeholders' authority to make decisions on matters "where they’ve done the most work." But as we’ve already explained, such claims about an absence of governance are misguided. Every open source project has a governance model. In the case of most do-ocracies, the governance model is merely implicit in the everyday interactions of project members. As a result, joining them can be difficult and intimidating for newcomers, as would-be contributors might not immediately know how to participate or seek approval for their contributions.

To get started in a project with this governance model: Find an aspect of the project you feel you can improve and simply begin working. Review the recorded history of changes to the project to identify the participants whose feedback will be integral to your successful contribution. As the project accepts more of your contributions, you will gradually accrue influence in the community. Do not expect to influence decisions in a do-ocracy until you are able to demonstrate a history of successful contribution.

The founder-leader governance model is most common among new projects or those with a small number of contributors (and since most open source projects have only a small number of contributors, this is a rather popular model!). In these projects, the individual or group who started the project also administers the project, establishes its vision, controls all permissions to merge code into it, and assumes the right to speak for it in public. Some projects refer to their founder-leaders as "BDFLs" or "Benevolent Dictators for Life," a term that is falling out of fashion.

In projects following the founder-leader model, lines of power and authority are typically quite clear; they radiate from founder-leaders, who are the final decision-makers for all project matters. This model’s limitations become apparent as a project grows to a certain size. Separating the founder-leaders' personal preferences from project design decisions eventually becomes difficult, and founder-leaders can become bottlenecks for project decision-making work. In extreme cases, founder-leader models can create a kind of "caste" system in a project, as non-founders begin feeling like they’re unable to affect changes that aren’t in line with a founder’s vision. Disagreements can lead to project splits. Worse, a founder-leader’s disappearance, whether due to burnout or planned retirement, can cause a project to disintegrate entirely.

To get started in a project with this governance model: Browse project mailing lists or discussion forums to identify the project’s founder-leaders, then address questions about participation and contribution to those leaders through one of the community’s public communication channels. Founder-leaders tend to have a comprehensive view of the project’s needs and will direct you to areas of the project that will benefit most from your contribution. Be sure to understand founder-leaders' vision for the project, as most founder-leaders will veto proposed changes they feel conflict with that vision. When starting out, do not expect to propose changes that will not serve the founder-leaders' vision for the project.

Recognizing shortcomings of the founder-leader model, the self-appointing council or board model aims to better facilitate community leadership turnover and succession. Under this model, members of an open source project may appoint a number of leadership groups to govern various aspects of a project. Such groups may have names like "steering committee," "committer council," "technical operating committee, "architecture council," or "board of directors." And typically, these groups construct their own decision-making conventions and succession procedures.

The self-appointing council or board governance model is useful in cases where a project does not have a sponsoring foundation and establishing electoral mechanisms is prohibitively difficult. But the model’s drawbacks become apparent when self-appointing governing groups grow insular and unrepresentative of the entire project community (as member-selection processes tend to spawn self-reinforcing leadership cultures). Moreover, this model can stymie community participation in leadership activities, as community members often feel like they must "wait to be chosen" before they can take initiative on work that interests them.

To get started in a project with this governance model: Because this governance model is typical of more mature open source projects, communities adopting this model will often curate getting started documentation aimed at assisting potential contributors. Find this documentation and read it first. Then read the project’s governance documentation to determine how its governing bodies are composed. In many cases, you can locate a council or board governing the part of the project where you would like to make a contribution. That body will be able to oversee your contribution and answer questions you may have.

Some open source projects choose to conduct governance through elections. They may hold elections for various roles, or conduct similar electoral processes to ratify or update project policies and procedures. Under the electoral model, communities establish and document electoral procedures to which they all agree, then enact those procedures as a regular matter of decision-making.

This model is more common in larger open source projects where multiple qualified and interested contributors offer to play the same role. Elections are also common for projects with a sponsor (a foundation, for example), because an electoral process can make the allocation of sponsor resources more transparent. Electoral governance also tends to lead to precise documentation of project roles, procedures, and participation guidelines. When election documents make these matters explicit, they help new contributors maximize their involvement in a project.

But elections also have drawbacks. They can become contentious, distracting, and time-consuming for all project members (whether those members are running or not). Some communities promote elections as a solution to the indefinite tenure of well-known project members; however, elections don’t generally cause turnover unless term limits are part of the project’s policies.

To get started in a project with this governance model: Communities appointing leaders through elections typically feature election results and a leadership roster prominently on their project websites. Review those documents to determine a point of contact in the project. Well-governed open source communities will it make clear on their project websites their processes for proposing and reviewing items that the community can vote on. As you establish a reputation for making useful contributions to the project, you may eventually decide to be a candidate for a project leadership position. Be sure to interact productively and collaborate effectively with other contributors as they may be voting you into a leadership position some day.

Occasionally, individual companies or industry consortia may choose to distribute software under the terms of an open source license as a way of reaching potential developers and users—even if they do not accept project contributions from those audiences. They might do this to accelerate adoption of their work, spur development activity atop a software platform, support a plugin ecosystem, or avoid the overhead required for cultivating an external developer community.

Under this model, the governing organization usually does not accept contributions from anyone outside it. Instead, open and closed source innovation occurs at the edges of the project, just where it contacts the rest of the world. For this reason, some commentators call this the "walled garden" governance model. Occasionally, projects following this model will adopt license with strong "copyleft" requirements, which they see as a deterrent to commercial competitors benefitting from their work on the project (the goal is to force competitors and customers with production requirements to purchase a non-open source license for the software—what some call a "dual-license" approach). This model becomes problematic in cases where a project claims to have an open community but is in fact wholly owned by a company or consortium.

To get started in a project with this governance model: First, consider any existing relationship between your employer and the company originating the project, if applicable. Next, assess the project’s licensing terms and review its change history and bug tracker to determine whether you are able to contribute to the aspect of the project that interests you—and in the way you would like. Given the project’s particular licensing stipulations, you may find yourself working alongside or on top of a particular project rather than contributing to it directly.

To exert greater control over resources and project code, some open source projects choose to be managed by an incorporated NGO (non-government organization), such as a charitable nonprofit or trade association. Doing this allows the "project," as an abstract entity, to take ownership of resources like servers, trademarks, patents, and insurance policies.

In some cases, foundation leadership and project leadership can form a single governance structure that manages all aspects of the open source project. In other cases, the foundation manages some matters—such as trademarks and events—and other governance structures in the project(s) control other matters (such as code approval).

Extensive funding and legal requirements normally limit this model to larger open source projects. However, many smaller projects choose to join larger so-called umbrella foundations, such as the Software Freedom Conservancy or the Linux Foundation, to reap some of the benefits of this governance model. This governance model is advantageous for projects seeking to establish legal relationships with third parties (like conference venues) or projects seeking to ensure successful leadership transitions following departure of key individuals. It might also help prevent the commercialization of the project under a single vendor.

High overhead—not strictly financial, but particularly in terms of contributor time, which can be substantial—is a significant drawback of the foundation-backed governance model. Some foundations are incorporated as industry consortia, in which sponsoring companies govern the organization. Different consortia allow different degrees of participation from individual project contributors; some are fairly open groups, while in others only corporate managers have authority.

To get started in a project with this governance model: If a foundation does not govern day-to-day project contribution activity, then locate the project’s getting started documentation and follow it. Otherwise, note that individual projects under a particular foundation’s umbrella will have their own sets of leaders, though some common guidelines may standardize basic contribution processes across all projects a foundation governs. To identify a specific project’s leaders, consider addressing a request to the foundation members' mailing list. You might also examine the project’s change history to identify frequent contributors and contact them. As many foundations feature a contribution-based voting system, familiarize yourself with steps required to become a full voting member of the foundation. If the foundation is a members-only industry consortium, determine whether your employer is already a member. If not, talk to your manager about the importance of the project to your work and ask whether your employer might consider joining. In either case, foundation projects may require signing contributor paperwork. Your legal department should assist with reviewing and signing such paperwork.

When writing governance documentation, it can be tempting to define your project as you would like it to be—or how your corporate marketing department would like it to be seen—rather than how it actually is. Particularly, project leaders frequently make the mistake of attempting to make the project appear more democratic than it actually is, in documentation. This falls apart when users or contributors expect your project to live up to its governance documentation, and it doesn’t. People who would have been fine with being told a project was single-company at the outset become very upset if they ask for their committer status and are refused later.

Like technical documentation, governance documentation should explain how things actually work. If there are aspirational goals, those go in their own section under "Roadmap" or "TODO."

As mentioned, your project will have a variety of real roles, but you only need to define a handful of them to start out. Those basic Roles are:

Whether you’ve thought about it, your project already features all these roles you already have in your project. Each one of them should be recorded in a roles document of some kind, either in your project’s documentation or your main source code repository. This allows you to make what was implicit into explicit, both setting expectations for and allowing more people to participate in your project. For each role, you’ll need to define who they are, how they qualify for that role, what they are expected to do, and what their rights and privileges are. Eventually you’ll go beyond these roles and define many more specific ones. But detailing these three will take your project a fair distance on its journey.

Creating a code of conduct (CoC) for your open source community is one of the simplest and most powerful ways to begin influencing the project’s governance model. A code of conduct is a description of expectations for community members' behavior when they act within or on behalf of the project. It might outline the values a community agrees to uphold, articulate the behaviors community members expect one another to exhibit in the service of those values, and identify the consequences of violating the code. The most effective codes of conduct are those written through collaborative processes that involve participants across the community (not just project leadership!). In this way, constructing a code of conduct can become a compelling community-building exercise.

Here are the core items that every Code of Conduct needs to have:

When you’re starting out, both the report recipients and the enforcers of the CoC are likely to be your project founders. As your project grows, you’ll want to form a specific CoC committee, but you don’t need that right away.

In order to recruit contributors, you need to tell them the basics of how to contribute to your project. For projects on GitHub or GitLab this is generally placed in a document called CONTRIBUTING.md, but it can really go anywhere as long as it’s linked from your project’s home page. If you’ve documented your Contributor role, you can just use that for your contribution docs. If you haven’t, then here’s a few things you should cover in your contribution document:

Some projects have paperwork that needs to be submitted before any contributions can be accepted, such as a Developer Certificate or Origin (DCO) or Contributor License Agreement (CLA), certificate of identity, or GPG keyring. Spell these out with step-by-step instructions in your contribution document.

Most open source projects have multiple ways that project members talk to each other, including email, chat, issues, code reviews, video conferencing, and even in-person meetings. You need to spell out which channels your project uses, and how to join them. It’s also important to keep this information up to date.

If you have them, it’s useful to list both your user forums as well as the channels used for contributors, so that people know where to take their questions. Distinguish the media used for official project business as opposed to unofficial channels used for general discussion. It’s extremely frustrating for contributors to be told "oh, we decided that on the mailing list" if they didn’t even know there was a mailing list. Any regular meetings should link to a calendar, or at least information about the next meeting. And if your community has any important events, such as annual developer conference, mention it.

Refer to this guidebook’s chapter on communication norms in open source projects for more detail.

If you’ve already documented your "leadership" role, the information on how project members become leaders will be part of it. However, some projects don’t get around to writing roles, and other projects have multi-step election procedures that require additional documentation. Some just want a quick-reference of how the election or selection process works.

If you have the typical new small project, this document will be very short indeed, containing simply the list of project leaders, who are also the project founders. If your project has a self-appointing council, it’s not that much more complicated; just write down how the selection works.

Projects that have full-blown elections will need a longer document containing all of the provisions of elections, including who gets to vote, how the vote is conducted and by whom, what the schedule is, and how candidates are selected. We’ll offer additional advice on holding elections at the conclusion of this chapter.

If your project has multiple levels of contributor status, with a defined progression between them—what’s known as a "contributor ladder"—then it can be useful to write a specific document explaining how this works. This will give new contributors an idea of what’s ahead of them and what they need to do to move up. It also helps make sure that contributor promotion is being done fairly.

For fairness, it’s preferable to make the promotion rules as objective as possible. For example, "Has consistently helped with code reviews in the subproject" is good, but, "Has completed at least 40 code reviews over the last three months in the subproject" is better. Quantifiable rules help you avoid overlooking contributors who are valuable, but not outspoken.

Smaller projects, with only a couple of contributor levels (e.g., Contributor and Owner), do not need a separate document for this.

Releasing software involves making decisions around what will and won’t be included in the current release. When a project is small, this is pretty obvious, but in larger projects with contributors working for multiple employers, deciding what stays and what gets cut can be political. Decisions about which platforms are supported can also be contentious. As such, when your project grows you’re going to want to write down some process around releases.

Some projects have defined release teams, in which case this document will be largely a collection of Role documents for the release team. In other projects, the maintainers do the releases, but even with those it’s worthwhile to explain how they decide what gets included. This doesn’t mean necessarily changing how you do releases, but rather just writing down what the real procedure already is, particularly the method of deciding which features and patches get left out. The process for writing and editing the release announcement is also worthwhile, especially if your project involves multiple vendors.

This document will also have lots of non-governance content, like the locations of the servers, the commands to build packages, and how long to wait for mirrors to sync. It’s expected that most of it will be technical instructions. Just don’t neglect the who and why along with the how.

Once your project’s code is being used in production by external users, managing security issue reports becomes a critical priority. While this topic could use an entire chapter on its own, there is some basic governance setup associated with handling security issues. This will include:

Confidentiality requirements are particularly important for both the security team itself, and for the programmers and security researchers with whom you work. For example, security researchers are willing to not disclose their findings to the public until your project does, but only if they are promised that your security team won’t do that either. In many projects, security team members aren’t allowed to share certain information even with their own employers.

When a project gets popular, both commercial and non-commercial groups want to use the project’s name, word mark, and graphical logo. Whether it’s just statements of support, a third party wanting to sell shirts with your project on them, or other projects that derive from yours, projects need these entities to be following some kind of official policy around usage. Even if the project has not filed for a trademark with any government yet, establishing a pattern of policy and permission will help protect your project’s name and marks in the future.

Such a policy consists of four things:

For the actual acceptable usage statement and guidelines, projects should obtain legal assistance. The governance part of this is selecting the "trademark team" (which could be an existing steering council, or similar), and how guidelines are updated and changed. In projects run by multiple technology vendors, it’s critical to work this out in the early stages of the project, because the project’s own sponsors will want to use its mark almost immediately. Make sure that responsibility here is shared between the stakeholders in your project.

Like security issues, the trademark team needs to be able to handle confidential contacts, because sometimes pre-release startups may want to use your project name.

Establishing franchise rules is critical. Some projects have allowed anyone registered for a project’s site to vote in an election—a very low bar—but have specified that only project committers could be election candidates—a high bar. However, almost all projects eventually broaden the pool of potential candidates to equal the pool of voters. Anyone who can vote in the election is therefore eligible to become a candidate.

Projects typically take one of three approaches to defining the electorate and candidate pools:

Defining an activity metric and minimum bar specifying what qualifies as "participation" can become contentious, mainly because it involves drawing arbitrary lines delimiting eligible participants. Generally, projects specify that quantified, ongoing participation is necessary to become part of the electorate.

One common election fear is ballot stuffing or cohort effects, where large companies dominate the representative bodies by having a large voting bloc, or where friends of candidates will pass the low bar to become voters simply to vote for their candidate. In most cases, however, such fears are unfounded. Technical communities often try to create rules to mitigate against possible abuses of the system, but in most cases, these rules are "premature optimization," which Donald Knuth, author of The Art of Computer Programming, has famously described as "the root of all evil." ^[9] Avoiding special rules—and addressing issues with the electoral process as they arise—is generally the better practice.

One final consideration is the process for becoming a candidate in the election. The most popular option is self-nomination, where candidates post election information and their reasons for running. Another option is nomination, which is often the same as self-nomination as the candidate typically asks people to nominate them and second their nomination.

Another complex community decision is the voting system. Any community will include people passionate about how to vote—and how to count votes. Without proper care, conversations about these issues can go on for months and result in proposals that are almost impossible to implement.

Most community projects have used:

Some projects continue to use alternative voting systems like "first past the post" or weighted voting systems, in which voters receive 12 tokens to allocate to candidates however they wish, and the candidates with the most tokens win the election.

Several projects use online counting software. Options to consider include:

If you are planning to propose an election system, begin with a mission statement. For example:

The mission statement clarifies several things: who is being represented by the elected body, what their authority will be, and why they are being elected. Once you have agreed on the goal of the elected body, choose the simplest ways to define membership in the body being represented. Then, choose the simplest voting and counting system possible.

If you notice a hole in the documentation for a project or team, approach the project leaders or ask on the community forum whether anyone is working on documentation for a topic. On a site that allows "issues" such as GitHub and GitLab, you can also request a document by creating an issue, but it’s simpler to start by asking informally whether someone is working on such a document.

If you find someone who is already working on a document you believe necessary, offer to become a reviewer. Sometimes you can even help as an author, but authors must be careful to cleanly and clearly separate the topics assigned to different authors. Documentation tends to be less modular than software.

If no one is working on a document, and the community or project leaders support the creation of a new document, the next question is: who would be the best author? The answer normally is: you. There may be other people with more expertise in the topic, but if they haven’t created the document already, they probably are unable to do so because they are busy, don’t like to write, or for some other reason. The best author is the one with the desire to write the document, and if you proposed it, you are probably that person. Subject matter experts can feed you ideas and review your writing.

At this point, make a formal announcement, such as by creating an issue. A due date is recommended, to provide some pressure to finish the document. Remember that a document needs to be reviewed, which could add several weeks to the project. It is also useful to create milestones, which could include:

To be accepted into a project, the leadership or advisor group responsible for the project must approve it. These leaders should be liberal in approving documentation projects, because any new document that is relevant to a project will usually prove useful to at least some members.

After you get approval to write a document from leadership, go through the following steps.

Writing is a skill with many levels of proficiency, but a few guidelines can help inexperienced writers produce a useful document.

Usually, the author should circulate an outline for review before writing the document. The outline ensures that all important topics are covered, but that the document won’t contain unnecessary topics. Reviewers can also suggest reorganizations. However, the author often finds reasons to add topics or move them around when turning the outline into the actual document.

References to related documents are an important part of most documents. Authors should do research to find relevant documents, as stated earlier, and include them. Inline links can be useful, particularly to send readers to background in case they have to learn certain basic information to understand your document. However, it’s generally most useful to provide a section of references as the end of the document.

A personal appeal from a respected friend or colleague is the most effective way to recruit new team members. When you find a project you support, think of other people who would be valuable additions to the team. After you learn enough about the project to describe its goals and how the team operates, reach out to prospective new members.

Most volunteers bring useful knowledge into a project, and learn more as they participate. You can share this in many ways: by answering questions on forums and chats, mentoring people, and showing up at group meetings.

The range of possible pieces of software that can be written for one field or another gives some idea of what can fit in here. This can mean specific technical skills, such as a geographer in a Geographic Information Systems (GIS) project. This can be general technical ability, which is often needed for complex problem solving.

Community managers are often seen as leaders, the people everyone can turn to, an inspiration for others to emulate. This seemingly high pedestal can be daunting, demanding a good deal of emotional intelligence and mental effort to deliver a community that’s not only growing but also productive.^[11]

When the going gets tough, it’s often our responsibility (and our desire) to pull the community through those times. But in order to do this, we need to be in top condition ourselves. That is, we first need to look after ourselves before we can look after others in any sustainable way. Otherwise, we’ll never be able to adequately face whatever is thrown at us—and something always is, when interacting with diverse personalities, resolving conflicts, making tough decisions, all while working towards future long term objectives. And that is why self-care is so important.

One of the first tasks on the road to self-care, then, is to be aware of how our own emotional states can impact our communities.

Emotions (both positive and negative) are highly contagious.^[12] Our emotional expressions have the power to unconsciously influence people around us, such that others may even begin unconsciously mimicking our own.^[13] If we are in a state of anxiety or stress, others will sense this and add to it with their own negative energy. We see this when dealing with particularly toxic community members infecting others, but fail to identify that we ourselves can unconsciously unduly influence others as well. Similarly, if we are in a genuine pleasant mood, then people tend to be driven by that positive mood and become more productive.

In short: In order to bring out the best in others we must bring our best to the table.

As leaders, we wield potentially immense power to make positive changes in our communities. Let’s use this power. Take every opportunity to utilize your influence for encouraging and promoting self-care—not only for the community’s benefit, but also for yourself. Educate yourself on what self-care looks like to you, and communicate that understanding with your team. Community managers don’t need to share their most intimate fears or anxieties. Yet simply initiating a conversation on the importance of self-care can be beneficial, not just for the team running the community, but for the entire community.

Identify and implement regular, dedicated time in your and the team’s workload to practice self-care. Set realistic expectations on deliverables and communicate frequently within the team the potential triggers of stress or strain that may require more downtime to focus on one’s physical and mental health.

By taking steps towards actively promoting and advocating for self-care, you prompt members following your lead to do the same. You also begin revealing your human side, eroding the unhealthy assumption that leaders are invulnerable to emotional dimensions of the work.

We can often find ourselves being controlled by unrealistic generalizations (either our own, or others') of what a community manager should be: driven, friendly, successful, super-human, even perfect.

However, these impressions of what a leader really "should" be are full of contradictions and fundamentally flawed. A leader can be many things to many people, but the most important aspect is that they are human: flaws and all.

And yet community managers may tend to over-compensate, attempting to live up to these leadership images—especially by suppressing and hiding negative emotions for fear of being seen as "too emotional" or, worse, "out of control."

But there’s a difference between being in control, being controlled, and being under control.

The belief that "being in control is a reflection of our confidence in what we produce" is inaccurate. It actually demonstrates that we are reluctant to show others that we are not perfect and struggle to accept anything less.^[14] Although maintaining this front can help shield us temporarily from others' emotions and criticisms towards us, it doesn’t protect us from our own self-destruction caused by bottling them up.

The consequences of suppressing your emotions will inevitably surface, and dramatically so. This is when our emotions control us (and our actions), which often leads to rumination, collapse of relationships with one’s team or community, and other negative outcomes like burnout.

The ultimate aim is to be "under control," both with your emotions and your workload. Here, our passion and attention are directed in a constructive and purposeful manner—a particularly important place to be in when we’ve made a mistake.

The phrase "bring your whole self to work" is a good expression of allowing yourself this forgiveness. We should feel like we can admit when we don’t know something, haven’t made the correct decision, or have made a mistake. And we should also recognize and accept that we can have good days and bad ones.

Being honest with ourselves is as important as being honest with our communities. If we’re not honest with ourselves and in tune with our emotional states, we may unintentionally escalate difficult situations within our communities (due to our failures at acknowledging that perhaps we should be stepping back until we feel we have more clarity to address the situation appropriately).

Maintaining this kind of emotional labor can be incredibly exhausting. We must acknowledge and accept that being perfect is unattainable, and more importantly, not a requirement for being a great leader. What is important is people can relate to your human side.

People gravitate to others with whom they share a kinship ^[15], and being able to identify this feeling of kinship is one hallmark of an effective community manager. If your members see that you possess qualities they can relate to, they can more easily empathize with you. Ironically, we often emphasize the significance of practicing empathy for our members or team, but it’s equally important that our members demonstrate compassion and gratitude towards us too.

As everyone on a team or in a community nurtures this empathy, they will gradually deepen connections and trust between them, which in turn can help them establish an informal social support network. This network can be a conduit for promoting the importance of self-care, creating judgment-free zones, or providing safe havens to individual members (including yourself) for emotional reflection, airing frustrations, or sharing workloads.

It is inevitable that some members will expect you to adhere to the pretense of being the all powerful, infallible captain of the ship, but with an effective self-care routine and the backing of the members within this social support network, you’ll feel more confident in your ability to handle those stressors. You’ll also understand that your vulnerabilities are what makes you a better community leader.

Physical self-care is usually the self-care we perform at a minimum, often subconsciously: feeding, hydrating, sleeping, and exercising.

However, we often find ourselves neglecting these necessities for the sake of work (enduring frequent all-nighters, for example, or forgetting to eat lunch every weekday). Keeping ourselves nourished helps us maintain bodily health. Getting into healthy physical self-care routines also helps us take regular breaks from our work—and our work environments.

Physical self-care might include activities like:

Mental self-care is the act of stimulating our mind with positive and purposeful thoughts to help reduce stress levels.

These are doing things that keep the mind engage at an intellectual level on topics that interest you or help de-clutter your thoughts to re-organize them.

Mental self-care is often less tangible than other types so it can be more difficult to see an immediate benefit.

However, with consistency of exercising mental self-care we will see it’s benefits shape and form healthy attitudes towards others aspects of our life as we will be more inclined to be mentally satisfied.

A few examples of mental self-care:

This type of self-care often gets wrongly associated with being solely about religion but it can be applied to everyone whether you’re religious, atheist, agnostic, or otherwise.

Spiritual self-care are activities that nurtures the connection between you and your soul, providing you a deeper sense of meaning, or understanding of the universe. The word soul is merely a representation of the entity or uniqueness you feel embodies you, this can also be your inner spirit, energy source, or another reference.

A few examples of spiritual self-care:

Regardless of the different types and activities of self-care we perform, the aim is to help us in a constant and sustainable way, to fight off and defend us against the negative effects of our role. By ignoring our physical and mental well being we will be more likely to succumb to the stress and fatigue leading us towards more dangerous chronic illnesses and syndromes, like burnout.

Burnout is extremely hard to detect as not only is it subtle and progressive, but it is often misdiagnosed as the earlier, more temporary, common work related stress. This is because the two are similar until it becomes too late and has developed into a much deeper and harder problem to treat.

Psychologist Herbert Freudenberger has released multiple books and articles since the 1970s regarding his research of the possible causes, implications, and affects of burnout. His work ^[19] has helped to define the different symptoms and thus the phases of experiencing burnout.

Perhaps you recognize several of them in yourself; perhaps you recognize only one or two. It’s not always easy to see the signs since not only do they gradually occur over time, but also hide behind our own denial of something being wrong.

Freudenberger and his colleague Gail North ^[22] later categorized the consequences of these symptoms into 12 phases of one developing burnout syndrome ^[23]. Similar to the symptoms, sufferers may experience episodes in multiple phases, not in sequential order, and for any length of period of time.

These distinctions help us to identify the deterioration in either our own, our team’s, or community member’s activities and their attitudes towards themselves and others.

It’s important to be self-critical and pierce our disillusion that everything is fine – it usually isn’t and it won’t "just work its way out."

We’ve identified the devastating effects of burnout now lets explore the possible sources for these symptoms within our role or even within the community.

We earlier described that burnout is a combination of many factors but a recurring element is the realization, subconsciously or not, that we don’t feel our work is providing us the same sense of reward and purpose as it had once done before.^[24] Rewards don’t always equate to money or status but can simply be the deeper satisfaction and pleasure in the adhering to one’s values and achieving happiness.

If you feel yourself or anyone else succumbing to burnout then the most direct approach is to take a break from the source of the stress, which is more often work itself, and reflect on the more acute causes of your burnout.^[26]

Work addiction, often referred to as workaholism, can affect anyone who is deeply embedded in an online community and often justifies their extensive work hours as commitment to the project. The inability to stop is often driven by the compulsive need to achieve status and success, or in some cases to escape emotional stress. Work addiction can be a vicious cycle where the feeling of achievement is an addictive "high" at the cost of our mental and physical well being, often not noticed until too late.

Work addiction, like other addictions, is difficult to acknowledge there is a problem to begin with. People suffering from work addiction are often in denial, convincing themselves work is a pleasure. Eventually this over compensation of effort and time, neglect of personal relationships and well being, leads to the inevitable experience of burnout.

It’s important we develop a healthy relationship with our role itself without feeling the need to be on the pedal at full gas. Try and assess what truly drives your motivations to achieve and does this require you to be online the amount of time you are. Do you find that you feed off external praise as form of validation of your work? Do feel that if you walked away from the community it would fall apart? Identify those moments of pleasure, whether it’s completing a task, or receiving a compliment from a community member or boss, and evaluate whether they are needed in the same doses you are currently experiencing them at.

We can also find that this need to achieve is a reaction to a heavy workload from the lack of resources within the team trying to prove to others the value the role and team brings to the project or company.

Reconsider these goals with the aim to reduce your workload. Are they achievable and maintainable with the current resources without sacrificing quality and a good work-life balance? If they aren’t, then consider prioritizing and communicating the most impactful goals that the team can achieve. Delegate any other tasks to suitable members or establish more flexible timelines, and anticipate time for possible firefighting as part of those deadlines.

Not only does this help to set reasonable expectations for the team members to achieve, but also promotes that a healthy work-life balance is an integral part of their schedule. This predictable schedule also helps you to provide better forecasting to the company or community.

When reflecting upon our work-life balance, it is important to establish clear boundaries between the two. As we’ve said earlier, due to our nature of work, we find ourselves participating within the community, and this begins to eat into our personal time, leaving nothing else. This is tolerable only on a temporary basis and only when we are required for an intervention, but this should not be the norm. Boundaries help us establish where our work ends, and pleasure begins. We’re not saying that work isn’t pleasurable, but having a variety of activities other than work helps stimulate our minds and provide alternative creative outlets.

These boundaries can also help the community acknowledge and accept your expectations of them as well of what they can expect from you. Be as transparent as possible by defining your available hours, and an escalation process for obtaining help outside of those hours. Highlight the importance of documenting community processes so members feel more informed on what they should do in incidences, with or without requiring assistance. The aim is to establish a consistent schedule, and to have the team and community respect it. Although they may not do so on every occasion, you will be able to use your boundaries to help prevent the feeling of guilt as you begin to embrace personal time as your own, as well as respecting others.

Of course if there are any serious incidences that require your intervention during down-time, ensure you put into place mechanisms for the team to handle them rather than you being the only one who ‘can handle it.' These mechanisms can be an escalation process or a team effort to respond and review the response collectively. This helps encourages the mentality that everyone can lighten the load, especially when it eats into yours and their personal time.

Maintaining personal boundaries is also extremely important as well. Our role often asks us to help members with their workload as well as interpersonal communication matters between themselves and other team members. But we need to be aware and recognize that we can’t solve every interpersonal issue or conflict–sometimes we just can’t become too involved.

As much as we don’t want to admit it, we must respect that we are not skilled or obligated to practice therapy if we feel it is required for a particular member. When the conversations or observations become more apparent in that direction, then aim to persuade them to seek medical or psychiatric help. Our role is to aid members, but there is only so much we can achieve from our position and that is OK.

It can be beneficial to partake in mental health training for you and your team to learn how to handle situations involving members in the community or team. This can help you apply a suitable process to follow upon if someone is beyond your ability and responsibility to help them.

Sustainability is an extremely important goal to have for a community, often seen as a contributing factor to the project’s own success. This should always be at the forefront of our minds when developing tools and processes for the community, with the aim for the community to become self-reliant, self-driven, and empowered. But there is a lot of work to be done to achieve this, and we need to ensure we and our team are able to keep up.

Things become unsustainable when we have set unrealistic expectations either upon ourselves or on the community. When it comes to ourselves we can underestimate our project timelines because we have attributed our motivation as part of the estimation: the drive that will get us over the last hurdle. Motivation is not an unlimited supply, and can fluctuate drastically due to external and internal factors. Try to extract motivation as a factor—although you may feel extremely excited about a project, don’t let that cloud your judgment on how long a project will take to complete. If not, you may see it negatively affecting your work life balance.

We tend to also inaccurately assume the motivation of others in the community. By definition community member are volunteers and, yes, we are fortunate to have those exceptional members that go above and beyond what is required. However, we should not expect the same of all, in fact we should expect delays and anticipate them.

By beginning to form clear boundaries, reduce your workload expectations, and improve estimations, you start to deliver on realistic schedules. Imagine you achieve a task within a week, rather than it taking triple that amount of time, because: you identified it as a priority; delegated other lower tasks to the team (or set the expectation it wouldn’t done at all); only worked within your allocated time; and were refreshed from recharging your mental well being with dedicated offline time. This combination of activities and processes was key to achieving success, thus triggering the event of providing and receiving continuous rewards, and helping towards reducing the probability of members developing burnout.

The only thing that is ever consistent is time, so be aware that you may find the same rewards you gave yourself and others, change over time. Take time out to frequently reflect on what drives you and your community, positively review how much you have progressed, and assess what resources you have to adjust project goals accordingly without interfering, if possible, with a healthy work life balance.

An important aspect of being a manager or leader is to provide good and constructive feedback to those that are on our team, as well as the community as a whole. We understand that feedback from upper line managers/other leaders and those that report directly to us is extremely important to understand their perception of us as a person and our activities representing them: if they truly reflect our efforts.

Retrospectives are now almost integral in software development teams to continuously improve individual or team performance and morale, and identify problems that need solving. However, we find we don’t often do a retrospective for ourselves, with ourselves.

Introspection is the examination of one’s own conscious thoughts and feelings. This can refer to the mental state or in a spiritual sense, one’s soul. Self-reflection, introspection, and self-care are all intertwined with the aim to promote and sustain a positive direction for mental growth and development.

Introspection is extremely important for ourselves to evaluate our purpose and happiness we get from our actions, thoughts, and behavior. Since work is a big part of our lives, we want to ensure our role within the community and at our company aligns with our values. Or else we will find ourselves becoming more and more dissatisfied by the role’s insufficient rewards.

But first we need to know what our values are, what qualities we enjoy out of the role, and the characteristics of the people we love to work with.

Take some time to truly answer these, as gaining this self-awareness does not happen over night. Use these answers to help you reflect on how you feel when you do the things you do, both positively and negatively. Journaling is often a good, yet simple, practice you can do to clarify your thoughts.

Practicing self-reflection can be difficult to begin with due to previously discussed inner restrictions we place upon ourselves as community leaders: the need of being invincible; distorted perception of our worth; and lack of visible support. However, in creating a routine of introspection and self-reflection as part of our self-care, we will begin to exercise more control over our emotions: have inner clarity on our long term goals, and ability to identify more solutions-focused activities rather than the previously emotionally driven ones.

This term was first defined by psychologists Dr Pauline Clance and Dr Suzanne Imes ^[27] in the 1970s as the internal experience one feels, despite overwhelming amount of evidence proving otherwise, that they are incompetent and that their success was a product of luck or fraud within their field of expertise.

Often those that experience impostor syndrome have a hard time internalizing and accepting their success by minimizing positive feedback and comparing other’s work to their own. This more frequently happens if we have started a new job, taken on new responsibilities or roles, or returned from a recent career break. In order to compensate for this chronic self-doubt we begin to work late, procrastinate, or try to justify our position in unnecessary ways.

Dr Valerie Young ^[28] further categorized these types of flawed thinking of what sufferers believe it takes to be competent into the following subgroups:

Since our role as community managers is relatively new and less established than other roles within the tech industry, we can find ourselves struggling to easily define and confirm our decisions due to the lack of expertise and documentation in this field. We can find ourselves feeling more aware of being identified as a fraud especially when the company or project has never had a community manager before.

However, there are ways to help keep impostor syndrome in check and increase your self confidence.

We understand the power of a community, the ability to bring people together and with the right directions—and a whole lot of love—we can move mountains. So why do we feel we can’t have the same mentality toward helping ourselves?

During stressful and tough times, whether it’s just a bad day, or more chronic episodes of illness, research has shown that having a strong—though not required to be large—social support network is beneficial to our well being ^[29] Without a social support network it can feel lonely and isolating which can lead into further depression and anxiety.^[30] Often it’s our social support network, even if we don’t think we have one, that first spots there is a change with our behavior before we do.

A social support network is made up of friends, family, and peers.^[31] Although this is different from a support group, which is more formal and often prescribed, a social support network is something we can develop as part of our community and team structure to help tackle stress, and promote self-care.

Look towards those around you who you have a good relationship with and you feel you can confide in them. When you are feeling stressed or want to simply vent your frustrations, come to rely on your social support network to let go in a safe and healthy way. This unburdening of tension helps untangle your emotions, seek clarity on an aspect of decision making, or just lightens your mood by the sheer enjoyment of speaking with them.

We may find that those within the community, whom we spend most of our time with, grow to be included in our social support network and that each individual provides us with a unique form of support to help in different ways in our lives. But also remember that we should also serve as a form of support to others.

The more education and communicating with our members about the benefits of self-care, the more likely we will see it being practiced and encouraged by others. This in turns helps create a more caring and accepting atmosphere in the community. Education can be in the form of discussions promoting self-care, celebrating mental health campaigns ^[32], adding to the community guidelines when on-boarding team members to speak to the team if their workload or other aspects is affecting their health ^[33][34], or organizing training for team members on mental health awareness.

If you see a member on the team or community showing symptoms of burnout then reach out to them and let them know you are concerned for their well being. Identify that you are there to support them and more often they will respond positively and work together to alleviate their stress.^[35]

However, it is important to make clear here that if we feel that we are unable to assist a community member’s emotional stress beyond our role’s capacity, then encourage that they seek professional health advice immediately. We may find ourselves feeling guilty we are unable to provide support, but we need to remind ourselves that we are not professionally trained and thus could provide—though well intended—ill advice.^[36] Remember that other emotions affect those around them including how member’s stress can affect ours.

Similarly in our own direct reports' one-to-ones ensure you also have regular one-to-ones with your line manager to highlight any problems you have achieving your workload or effecting your well being. Be as direct as you are with helping others, as you are with yourself.

Later in this chapter we look at how to conduct an audit that measures the health of this aspect of a project. In that audit, you’ll see the main top-line questions from here as categories for more in-depth questions. Those questions in the audit section go into further details of the category.

This is a highly subject mix, and as a project ourselves, the authors of this guidebook are still exploring this material. For this chapter, we offer a list of considerations that seem generally applicable.

Imagine if you grow a garden and are very ambitious. The first year you overplant and are unwilling to thin out the seedlings. You end up with overcrowded, unhealthy plants.

In online communities (including open source communities), there is a strong drive for immediate and explosive growth. This is usually achieved by promoting the project in as many environments as are appropriate, with the result that many people join the community out of casual interest. There’s often a strong impulse to accept early adopters as committers, to create the impression of a viable, strong team.

Contributing community members—those who affect the actual direction of the project—should be chosen based on how much they actually contribute, and the value of their contributions, and overall consensus. If someone contributes fixes to a number of critical bugs, perhaps they should get write access for the project (and a corresponding voice); if, however, that same person creates a poisonous atmosphere for the community, then promotion to maintainer is not a good idea.

It’s also worthwhile to take note of core community members, rewarding those who contribute regardless of coding ability. For example, consider someone who is great at helping new users but hasn’t tried to fix bugs—recognizing those contributions creates a positive impression for that user and everyone else. Positive motivation encourages others to do what garnered the reward, which in turn makes the entire community more strong.

Growth should always be encouraged, by the entire community; just try to assure that the growth is composed of candidates who’ve earned membership. This does not mean that everyone has to get along perfectly at all times; personality conflicts are certainly possible (and likely, in some cases). However, the community at large shouldn’t allow specific members' opinions to make primary decisions like this; seek consensus rather than responding to the urging of a small subset.

Of course, a member’s actions might be severe enough to warrant a response. Use reason; consider whether anyone would be caught by surprise if an action is taken.

Fail spectacularly, and don’t forget to take notes.

There is a lot of crowd wisdom at work here. It’s basic physics, too — if you charge ahead and fall on your face, you at least made headway. Like feeling your way around in the dark, each touch, bump, and stub of the toe teaches you more about the environment.

When you drive your processes and technology to the brink of failure, repeatedly, you get very comfortable somewhere most people don’t even want to go. You also get to set a new standard for what is comfortable for your community, giving you new room to expand even further.

One of the most important elements of an open source community is the level and quality of transparency. Humans need private space, for certain, and that supports our ability to conduct ourselves in public space. Ultimately, all discussions and decisions need to held in front of the entire community. This builds trust, handles objections by including feedback as solutions along the way, and builds toward a community acting as a chorus. Key parts of this element include:

It’s crucial to the success of an open collaboration that no part of the work is held back "until it’s just right."

Many of us have the tendency to keep code, content, or ideas to ourselves until we get them finished enough, polished enough for others to review. In open source development methodologies, that perfection seeking is the enemy of the good enough.

Innovation is a process of building on existing ideas, in novel or even repetitive ways. We need others to see our ideas early and often so their influence can improve the ideas before they are too fixed to be improved.

Make it the rule that nothing is held back until finished. Treat it like a Zen practice—release early and often, every day or every hour if need-be.

It’s easy to say, "We designed this for such-and-such a reason for this particular audience." It’s not so easy to be the only creator and maintainer, though. If you want to grow beyond just you and your niche group, you have to be willing to accept the influx of new ideas and directions that comes with open collaboration.

There is a lot of disagreement over how fast an open source project should move. Many projects have found the six month release cycle is not too long nor too short.

Regardless of what type of schedule you choose, you need to stick to it and keep your community informed about the status of the schedule. Remember, it’s OK to disappoint people sometimes, but not surprise them.

There are two main types of schedule for delivering open source:

One reason time based schedules are used so often in open source is that it forces developers to release early and often, and not sit on code waiting for a feature to be completed. Incremental updates provide the community a chance to keep up, help, and contribute.

Even if you follow a feature based schedule, it is useful to break it down to smaller, time-based deliverables. This keeps your community interested and able to test, knowing that at regular, predictable intervals there will be something for them to try out.

People of all ages and experience levels have knowledge and curiosity to contribute. You can engage with what they know and what they want to know by putting yourself in the position of learning from them, even as they may be learning from you.

Part of practicing the open source way is teaching others about how and why they want to adopt this way of working, thinking, and acting.

In all your interactions, it helps for you not to presume that you are an expert and know all there is to know. Even in domains you are familiar with, ask basic and dumb and open and revealing questions. Ask any questions that help you make sure to reveal and map the principles of The Open Source Way to an individual domain.

Open projects need to have low barriers of entry. People and organizations are giving of their time and other resources, so if you are going to make them leap over any barrier, it needs to be a clear barrier with a clear reason. Otherwise, it’s an invisible problem that makes people disappear before you even know they are there.

If new participants come along and run in to a real, implied, or accidental barrier, a certain percentage of them will just walk away at that moment. At the very least, if you inform those people of what the barriers are and why they are there, then these folks will walk away informed instead of bailing out of ignorance.

If you want open collaborators, you must make all barriers as low as possible. You must advertise this access-level clearly.

If there are levels of access, such as "can write to the mailing list and file bugs" all the way over to "can commit major code changes to the source repository", then you must make it clear what these levels are and how to obtain them.

Wikipedia is an example of everyone entering at the same level. There are, however, community levels that are implied and centered around a group of information pages. It is easy to make an edit on a page, even anonymously, but to get that edit to stick (not be reverted by another page watcher in the information community), other, more invisible barriers need to be overcome. This may discourage some casual editors, if the information community around a set of pages are very strict about allowing anonymous edits. Other pages may not have that strict of an information community around them, so anonymous edits are stickier. In the end, this may affect Wikipedia’s reputation—some people have experienced or perceive that Wikipedia has an invisible barrier to entry they can’t see or overcome.

People want to see themselves and to see what others are up to. It is why sitting at a cafe is considered more special than having coffee at home. It is a social space, just as the elements of an open source community happen in social space.

Build systems and processes that make it easy to highlight the activity within the community. In some cases, this might be gamification, with badges, leaderboards, and the like.

In most cases, this includes making sure that everyone is acknowledged by name and type/area of contribution when you conduct a release.

Make your community culture be to document answers when asking for help. Ideally, the documenting should be done by the asker. And systems should make it easy for them to do so.

People offering help can require that the help be documented.

When the asker is a new member of the community, this is a great way to turn them into an instant contributor.

These four virtues were described by Brian Fitzpatrick and Ben Collins-Sussman in their seminal talk on avoiding poisonous people in communities.

These virtues need to be implemented in every part of the community. Public and private discussions, all communication channels from in person to IRC, and sometimes even in the nature of the project itself.

This is something that comes from your initial project and community planning. It should form some part of your metrics plan, the way you measure the ongoing health of your community for what it provides to its members.

When there is evolution in thinking here, as the project changes, this clear understanding needs to be updated. There is a side-effect of feature creep—the phenomenon of how the quantity of features increase via input from users and stakeholders while development is underway. Features that creep and sneak their way into a release may end up attracting more and different users and contributors.

These new people are not a bad thing in any way. But if they are unexpected and unnoticed, they become an underserved part of the community. In their bubble, this underserved group has its own understanding of what the project and software needs to do for them. Until you open that bubble and include them in the community view as a whole, their entire worldview is at risk whenever a change comes through the project.

Governance is not a static document and process to be adhered to year after year.

As the project evolves along many lines, so should the governance evolve in response, and even in anticipation.

You should have robust change management for governance and encourage it to be used early and often.

Governance is covered further in the chapter "Project and Community Governance".

Whoever is in charge of the largest or smallest things, it needs to be clear who they are, how to reach them, and so forth.

Leaders should be out in front, doing the work with others.

This is all part of the idea of what some call a _do-ocracy—a culture of those who do things become responsible for getting things done.

In healthy projects, members have formally documented release processes and identified release managers to supervise those processes.

Healthy open source projects have publicly shared goals and clear processes for reaching those goals. Goals are attainable and clear deadlines exist for tracking progress toward those goals.

For any organization, you want to have a set of objective measurement to help you understand how you are performing. For businesses, it could be things like revenue, new customer aquisitions, costs, etc. that you can look at periodically (e.g., quarter-over-quarter) to see how you are progressing. For open source projects, it is also helpful to have a set of metrics that can help measure the health of your community. These could include things like number of contributors, how long it takes to close bugs/issues, responsiveness of reviewers, contributor diversity, etc.

Transparency is a key ingredient in all open source projects, so it is important to have insight into all contributors to your project. This isn’t necessarily to rank or highlight the most active contributors. Rather, this is to get a better sense of where the contributions are coming from (e.g., different geography, organizations, etc.). When you start going beyond 20-30 community members, it starts to become more challenging to have a good insight into all contributors if you don’t have a good set of metrics.

Community metrics will not necessarily provide a full picture of the community, but they do offer important insight into the state of the community. For example, metrics can show if there are regular activities on project’s code, bugs/issues, documentation, etc. for the project. Also, when people join a new community, they typically struggle with identifying and connecting with more experienced members. If the metrics dashboard includes a list of active documentation contributors, that could be useful for anyone interested in contributing to project documentation. Some communities even have a dashboard of first time contributors to highlight new community members. These may seem like small things, but they could go a long way to help new community members onboard into a project and feel welcome.

As open source projects grow, you will typically face challenges with responsiveness to community members. For example, code reviews may take longer or you may see a growing backlog of issues. If you have a good set of metrics (e.g., average time to close issues, median time for code review, etc.) that you review on a regular basis, they could serve as early warning signs before you start to have a number of dissatisfied community members.

An open source project’s life cycle affects many other considerations about a project’s health. Understanding the project’s place in that life cycle will help you contextualize your assessment (e.g., single-person governance can be common when a project is young—but less effective when a project is more mature). Monitoring contributor trends might reveal critical information about a project’s short-term or long-term future.

When assessing the project’s life cycle, consider questions like:

Well-run open source projects demonstrate a clear understanding of the users (and contributors) they hope to assist and engage. When assessing a project’s intended audience, consider questions like:

Governance refers to the rules and customs that define who does what in an open source project and how they are supposed to do it. Healthy projects entail thoroughly documented (and continuously evolving) governance models. When assessing a project’s governance, consider questions like:

Refer to this guidebook’s chapter on governance for more consideration of this topic.

In healthy projects, leaders are visible and easily identifiable. Leaders often coordinate project work and establish a project’s vision, and usually have extensive knowledge of project history. When assessing a project’s leadership, consider questions like:

In healthy projects, members have formally documented release processes and identified release managers to supervise those processes. When assessing a project’s release manager and process, consider questions like:

Healthy open source projects have publicly shared goals and clear processes for reaching those goals. Goals are attainable and clear deadlines exist for tracking progress toward those goals. When assessing a project’s goals and roadmap, consider questions like:

New contributors are vital to project innovation and success. Healthy projects feature clear, welcoming onboarding materials that assist newcomers who wish to participate in the project. When assessing a project’s onboarding processes, consider questions like:

Communication channels are key indicators of project health, as are a project’s internal communication practices. Issues affecting community health often emerge first in internal channels—such as mailing lists or chat platforms—where contributors and users interact. When assessing a project’s internal communication, consider questions like:

Refer to this guidebook’s chapter on communications norms for more consideration of this topic.

Outreach is the process of actively promoting a project and making others aware of it. Communities use written materials (e.g., social media, blogs, whitepapers), events (e.g., meetups, conventions), and educational tactics (e.g., demos, training sessions) for outreach. Healthy projects have adequate energy and resources devoted to outreach. When assessing a project’s outreach efforts, consider questions like:

The project’s intended audience must be aware of the project and understand the problems it solves. Awareness is a desired outcome of a project’s outreach efforts and can be measured through user and contributor surveys or general marketing analyses. When assessing a project’s awareness, consider questions like:

No project exists in a vacuum. Projects frequently depend on one another. In some cases, similar projects can be competing to reach the same intended audiences. A community’s interactions with other projects in its ecosystem reflect the project’s health. When assessing a project’s ecosystem, consider questions like:

In the past, many people wrote complex scripts/queries to get metrics for their communities. Nowadays, most of the software tools (code repositories, forums, issue trackers, wiki’s, etc.) that open source projects typically use have APIs, plug-ins, or even built-in dashboards that makes it easy to collect data for your community. So if you use tools like Discourse, GitHub, GitLab, Jira, or others, you may be able to save a lot of time by reading their documentations prior to implementing a new set of metrics from scratch.

Not surprisingly, there’s an open source project that is focused on community metrics. The project is called CHAOSS (Community Health Analytics for Open Source software) and it has community members from academia, companies that participate in many open source projects, open source foundations, and others. If you visit the CHAOSS website, you will find details on metrics across different categories plus implementation examples for many of these metrics.

If you browse through CHAOSS metrics, you will likely find plenty of metrics (and implementations) that will be applicable to your community. If you have an idea for new metrics that are not yet in CHAOSS, you can also start a discussion on new metrics in the CHAOSS community.

A number of open source communities have good documentation/code for their community dashboards that many other communities can take advantage of. Many readers may be familiar with the CNCF dashboard and you can find details on their devstats project for their dashboard in the CNCF’s repo at https://github.com/cncf/devstats.

Another good example is the Ruby community dashboard and their FAQ page, which provides good insight into why they developed the dashboard and some of their implementation decisions.

Some communities publish contribution metrics after each release. Here is a good example from WordPress after their recent release, where you will see a lot of good visualizations for where the contrbutions are coming from.