In the United States, often, when a family moves into a new neighborhood, there is what’s called a “welcome wagon” to help welcome people to the area. It’s not a literal wagon (at least not here in Doylestown, Ohio). Instead, it’s a group in a community that gets together and provides welcome gifts to someone moving into the area to help them get to know their new neighbors, and vice versa.
The idea of the “welcome wagon” is to help a new neighbor get past the awkwardness of getting to know a new group of people. As adults, it can be challenging to meet and make new friends, so local customs such as the “welcome wagon” help break the ice, so to speak, with the hope of integrating newcomers to the neighborhood into its activities and social circles.
Too often, open source projects look at themselves and say, “why isn’t anyone contributing to my project?” There can be multiple aspects to this, whether being unable to find out how to contribute, feeling intimidated by donating, or thinking they have anything of value to contribute. As with the “welcome wagon” in neighborhoods, good open source projects look to bring in and make the community feel welcome. It might not be a basket of cookies or a casserole as with the “welcome wagon,” but it can be as simple as a thank-you in a pull request, a mention in a release note, or dropping a sticker in the mail to them.
With burnout as the number one challenge faced by open source projects, this chapter will focus on ensuring your project is welcoming to new contributors. We will cover some of the basic things a project should have, how to best support end users, and embracing community-driven collaboration. Specific topics we will focus on include the following:
Let’s start with the basics – getting the project set up for newcomers.
The first part of having a welcoming project is to give the appearance that maintainers want newcomers. That might sound flippant, but too often, it doesn’t appear that way. First impressions are everything in an open source project, and how your project is perceived is gauged by that first impression. Individuals and organizations use, participate, and invest in projects that they perceive to be run well.
Let’s kick things off by looking at the basics of the infrastructure.
When you first come to an open source project, you likely have several expectations.
First, you want to find the code itself. We see most projects these days leverage a service such as GitHub or GitLab, which offer free code hosting services to open source projects. Additionally, there’s the advantage of being close to other open source projects, which can help your project be more naturally discoverable. When you come to a project, the first file you often look for is the README file. If you are looking for guidance on setting up a README file and other governance-related files, review Chapter 6, Making Your Project Feel Welcoming.
However, a good open source project has much more than just a README file; it has different channels for communication. Things to consider include the following:
Not all projects use all of these mediums. Good projects though tend to use a few of them. Here are some good rules of thumb:
Now that you have a good project infrastructure setup, let’s put out that “welcome mat” and look at how to build a great getting started guide.
There’s a general ethos amongst those in user experience design circles on the importance of the “first 5 minutes” that a user uses an application. If a user is successful in those first 5 minutes, it’s usually a good sign that they will become a long-term user. On the flip side, if a user isn’t able to be successful in the first 5 minutes, you’ve often lost them. Open source projects are much the same, even with a more developer- and hacker-oriented crowd; if someone can’t figure out how to use the code quickly, they will move on to the next project.
Getting started guides can vary depending on the project and technology. For a command-line tool, using the --help command-line switch or using man should trigger a usage guide. Here’s an example for the asana-cli project (https://github.com/AlJohri/asana-cli):
$ asana --help Usage: asana [OPTIONS] COMMAND [ARGS]... Examples: asana list workspaces asana list projects --workspace="Personal Projects" asana list tasks --workspace="Personal Projects" --project="Test" asana list sections --workspace="Personal Projects" --project="Test" asana list tasks --workspace="Personal Projects" --project="Test" --section="Column 1" asana delete tasks --workspace="Personal Projects" --project="Test" --section="Column 1" asana mark tasks --workspace="Personal Projects" --project="Test" --section="Column 1" --completed asana mark tasks --workspace="Personal Projects" --project="Test" --section="Column 1" --not-completed asana move tasks --workspace="Personal Projects" --from- project="Test" --from-section="Column 1" --to-section="Column 2"Commands: Options: --help Show this message and exit.
In this case, the guide connects a few common use cases to the commands used and then the full set of command options available. This is the appropriate level of detail for people used to working with a command-line interface and Asana. It also does a good thing by putting the getting started guide in the flow of working with the tool, meaning that the user has to go nowhere else but the command shell to understand how to use it.
For more complex projects with different use cases, a deeper guide tends to be a better approach. Let’s look at the GET STARTED page for ONNX as an example:
Figure 6.1 – ONNX Get Started page (https://onnx.ai/get-started.html)
This page presumes the user already understands machine learning models and has a model to use with this tool. So, the first task the user sees is getting that model into the right format for the deployment option they choose, because otherwise, the tool isn’t very useful. This is a perfect approach for the audience and is a big part of making sure the user is successful in the first 5 minutes.
We’ve seen from these examples two common themes to have in mind when you create a getting started guide:
A getting started guide serves as the digital presence for welcoming people to your project. Still, as people look to engage more profoundly, they will start to connect with maintainers and contributors. How that experience goes is key to someone wanting to continue being involved. Let’s look at some strategies around being welcoming to new contributors.
As we learned in Chapter 1, The Whats and Whys of Open Source, in the early days of free software, generally, software was developed “behind the scenes” with limited end user involvement. There was a multitude of reasons for that, but one was that end users were generally considered not to have the right level of knowledge of the domain or project design to be helpful. We see this carried over to open source projects today occasionally, which can be a deterrent and hurt the later growth of a contributor into a maintainer. We will see more on this in Chapter 7, Growing Contributors to Maintainers.
Contributors are quite often intimidated by a project; a project has people they may not know, people from a different race, culture, gender, or region, or even people that might be high-level experts in a particular domain. Many software engineers have trouble bridging those social dynamics, so being on top of things is a good way to ease that worry.
The hyper project does a great job of this with their contributor’s guide:
Figure 6.2 – Hyper Contributor’s Guide (https://hyper.readthedocs.io/en/latest/contributing.html)
What is great about this is it doesn’t start with the rules and processes – it starts with appreciation. That immediately shows the project is welcoming.
Having the first personal interaction be positive is another key to success. Let’s look at another example in the just-the-docs project of responding to the first pull request from a user (that user being me):
Figure 6.3 – Pull request response (https://github.com/just-the-docs/just-the-docs/pull/726#issuecomment-1063254623)
Here, the project representative is humble at first; the maintainer realizes I contributed nearly 5 months prior and acknowledges that as part of the thank-you. As a contributor, this tells me that they weren’t ignoring me on purpose, just that life got in the way, and they still appreciate my contribution. Secondly, the maintainer replies by asking me to add documentation, but not in the form of, “You obviously didn’t read our contribution guide because otherwise you would have known to do this.” Instead, the maintainer positions it in terms of value (wanting to make sure others know about the new feature) and offers guidance on where to add the documentation. If you read the entire pull request, you’ll see the maintainer continues to help me to make sure the placement and form of the documentation are correct.
You see the themes of “helpfulness” and “humbleness” as attributes of both examples. When I talk with project leaders, I share that leadership in open source is “servant leadership,” meaning the project leaders are there to ensure the community of contributors and users have what they need to be successful. Keeping that mindset toward all contributions, even challenging ones, helps set the right tone on how a project looks at its contributors. More on this in Chapter 8, Dealing with Conflict.
Welcoming is the first step in making a newcomer want to stay around, but to keep someone around, the project must show how they value a newcomer’s contributions. Let’s look at ways to quickly and meaningfully recognize newcomers when they make an impact.
Newcomers often see contributing to open source as a way to establish their portfolio of work for potential employers, as these code contributions help showcase the skill a developer has. We will dig deeper into this in Chapter 11, Open Source and the Talent Ecosystem, but knowing this, it’s important to recognize contributors for their own career growth in addition to showcasing your project as a welcoming one for newcomers.
Every project has a way to recognize newcomers, even if they have no funds. A simple way is a thank-you in the release notes; here is an example from the just-the-docs project recognizing not only the new feature but also the contributor:
Figure 6.4 – Recognition of contribution in the release notes
What’s nice here is that this becomes searchable within GitHub as me being a contributor and something that I could link back to.
If you have a budget, then there are a few other options you can choose from:
We’ve looked at several key pieces and practices in the project setup for newcomers to the project. One big reason people come to a project is to get help, so let’s look at ways to support end users effectively.
Open source projects generally aren’t set up to provide the level of support you need for a commercial product and for good reason. First is that just from a staffing point of view, there’s rarely the capacity to dedicate the same level of support. And second, in open source, we see a community model, meaning we users help other users, and sometimes bugs and workarounds are worked out together in the open rather than behind closed doors.
While a project can learn from commercial products on strategies for supporting end users, there are some nuances in doing so in an open source project. Let’s begin by looking at what effective support looks like with one of the first touchpoints an end user has with the project – submitting a new issue.
We talked earlier in this chapter about project infrastructure and in Chapter 5, Governance and Hosting Models, about the importance of a README file to guide newcomers on the governance of a project. One piece of that governance is how to raise issues, and it is also one of the key questions someone will look for an answer to in a project.
Some key attributes of good issue management include the following:
Having a good issue management process shows end users that you value their feedback and appreciate them as users, but submitting an issue isn’t the only way that end users engage, so let’s look at broader community and developer management strategies.
As a project grows and many users use the project in various ways, you will see a natural community form around it. This happening is a great thing – and these communities can take on a life of their own (more on that in the next section of this chapter), but it also requires work for the project to manage.
When I use the word “manage,” this isn’t about control but more about support and guidance. Think of the reason people use an open source project in the first place; it solves a problem they have. When the user comes to a project, they are looking to solve that problem, and the role of community and developer management is to be a guide. Good community and developer management has these attributes:
A great example of the value of good community and developer management is looking at when Apache Cloudstack and OpenStack were the two predominant open source projects for Infrastructure as a Service (IaaS). Both technologies were fundamentally sound, and each had something that the other didn’t. However, in the end, OpenStack came to be the market leader. Why was that? OpenStack heavily invested in community and developer management, which helped users and developers be more successful quickly, and helped the project itself grow to solve the problems the users had.
While a vibrant community can provide an immense amount of support for an end user, it’s never going to be at the level that commercial support would be. Let’s look at how to best have commercial permission to support end users effectively.
We spoke at the beginning of this section about how open source projects are not set up to offer commercial support, but that doesn’t mean that other companies can’t step in and offer it.
A great example is in the Linux distribution space, where among a vast number of Linux distributions are several that offer commercial support (examples include Canonical, Red Hat, and SUSE). Each of these distributions is offered for free or has a free offering, but at the same time, they can provide the level of commercial support that a larger company would require. After all, not many open source project maintainers want to be fixing bugs at 11:00 P.M. on Christmas Eve.
We see more formal models of this in other projects. The Kubernetes Certified Support Provider (KCSP) program (https://www.cncf.io/certification/kcsp/) provides a mechanism for vendors to indicate that they offer commercial support for Kubernetes. What’s nice about this program is it’s not run by any one vendor, but by the Kubernetes community itself, so end users have an unbiased and objective view of the service providers, knowing that the community sets objective standards around training, business models, experience, and upstream support. This program in particular requires vendors to be members of the Cloud Native Computing Foundation (CNCF), which means some of the revenue they take in from support is funneled right back into the project for infrastructure, events, and community support.
A key takeaway is that commercial organizations getting involved in an open source project is a good thing, just as we discussed in Chapter 4, Aligning the Business Value of Open Source for Your Employer. As described in Chapter 5, Governance and Hosting Models, good governance helps ensure vendor neutrality for a more collaborative project.
We’ve looked at some strategies for supporting end users in your project’s community. What we often see in vibrant communities is that the community starts to form new spaces for collaboration, which can be helpful for the project but also does require some degree of management from the project. Let’s look at this now.
Nearly all the best things that came to me in life have been unexpected, unplanned by me.
– Carl Sandburg
Open source communities are not something you can completely design. Indeed, you can provide infrastructure, support, and guidance, as we’ve spoken about in this chapter, but the magic of them is when they take on a life of their own. When I was a community manager at SugarCRM, I remember always being amazed and delighted at the interesting extensions that the community members built and the motivations behind them. Linus Torvalds did an interview a few years back, and when asked about what was surprising about Linux development, he said the following:
“What I find interesting is code that I thought was stable continually gets improved. There are things we haven’t touched for many years, then someone comes along and improves them or makes bug reports in something I thought no one used. We have new hardware, new features that are developed, but after 25 years, we still have old, very basic things that people care about and still improve.”
(Source: https://www.linux.com/news/linus-torvalds-explains-how-linux-still-surprises-and-motivates-him/)
We often see virtual collaboration as the first channel to take off for communities, so let’s look at how to best manage online forums and social media.
As we’ve seen technologists and open source enthusiasts grow in their careers, you tend to see them congregate in different online communities. Back in the early days of open source, we saw platforms such as Slashdot as the center of gravity, and over time, newer platforms such as Reddit, Stack Overflow, and Hacker News have become the center point for these discussions. Add to that the growth of social media and it can mean your project can be talked about all over, but it might be hard to stay on top of the conversation.
Some projects become concerned about conversations regarding their project for so many reasons, but I’d argue to embrace it. Communities in which collaboration only happens through specific forums or mailing lists can become an unintended “walled garden.” But it’s not easy – here are some tips and best practices:
One thing I will say from personal experience as a community manager is that managing all these online forums and social channels can be taxing. It’s easy to get caught up in discussions, and before you know it, a full day has gone by. Think about smart engagement and management; one tip I would share is to limit how much time you spend on this in a given day/week and try to stick to that. It’s okay if you miss a post out there; what I have found out is that on the online forums and social channels, you see the participants starting to do the work for you.
Community members often start with virtual engagement and then move to more direct engagement with peers in the community. Let’s look at the role of regional meetups and events.
Meetups and events are a large part of the open source culture. They are also crucial for sparking collaboration. If there is one thing I’ve seen as we’ve emerged out of the COVID-19 pandemic and started to be a part of in-person events again is that face-to-face interactions spark innovation and collaboration. Online collaboration can provide some of this, but it’s so much more natural and organic in person.
Having your project be part of events such as these is an easy way to increase its visibility:
Communities from digital and in-person collaboration start to gravitate around natural leaders and influencers and having a project recognize them helps motivate the person and guide the society toward them.
Being supportive of the community taking on a life of its own is a validation of the value of the open source project. That doesn’t mean it’s always easy, and we will dig more into this in Chapter 8, Dealing with Conflict.
This chapter covered several aspects of making your project feel welcoming, including having a good project infrastructure, a positive and inclusive culture in bringing in end users, and enabling the larger community to showcase the project in new areas and drive collaboration in different arenas. We scratched the surface of community management, and there are entire books out there that go deeper into the topic, which would be great reads if you have more interest in this area.
A key aspect of making newcomers feel welcome is supporting them in becoming contributors and maintainers over time. Let’s look at this in more detail in our next chapter, Chapter 7, Growing Contributors to Maintainers, and see how to help contributors make that transition.