At its beginning, every open source project starts with code, and one or more developers. What turns that project into a community are the people who engage with each other around that code. No matter what the maturity level of your project, one of the most important things to encourage and maintain is engagement with the users and contributors of your projects.

When a user of your project makes the effort to engage with the developers of the project, treat it as you would a gift from someone close to you. This person has taken time that they could have spent on something else, and they have chosen to spend that time contacting you. Whether it is a bug report, a feature request, or a pull request, these first interactions are critical to whether that person will have a positive or a negative impression of your project.

Here are a few things you can do to create a welcoming culture that treats user engagement as the gift that it is.

Accept the Gift

Sometimes it can be hard to react positively if (for example) a user is upset because something does not work as they expect in your project. At times like this, remember that this person is making an effort to tell you about their issue. Think of it like the time that your well-meaning aunt got you the cheap knock-off building blocks instead of the Lego set you were hoping for. When someone engages with your project for the first time, you have a one-time-only opportunity to give them a good first impression.

First, thank the person for their contribution, and acknowledge it. Many times when people turn up to your project upset, the very first thing they want is reassurance that it’s not them--reassuring them that, yes, this is harder to use than it should be, and helping them over the particular speed bump they are hitting, will turn them from critics to cheerleaders for the project.

Provide Actionable, Useful Feedback

In the case that someone is asking a question, you may need more information from them. If you are reviewing a pull request that does not match the project’s coding conventions, you will want them to make some changes to their contribution. In the case where you are giving feedback or asking for something from them, it is important to look at your project with a beginner’s eye. There is nothing more frustrating than having a question answered with “Just frobding the dollygagger,” and scratching your head and saying “How on Earth do I do that?”

When reviewing code, do not assume a high level of proficiency with the programming language, your project, or even with how to update a pull request in GitHub. If your project runs on Kubernetes, do not assume that the person you are dealing with is an admin on the Kubernetes cluster, or is familiar with Kubernetes internals.

If in doubt, you can always ask some level-setting questions, but if you are telling someone to change an option in a config file, give instructions on where to find the file, and what the file’s format is in. If the person you are dealing with cannot act on the feedback you are giving, the feedback is not actionable.

Give Engaged Users a Good Experience

When someone engages with your project, do everything in your power to ensure that they come away feeling good about the interaction. This is important not just for the person you are dealing with, but for all of the people you never hear from who are looking on. Whether it’s a reader who finds a StackOverflow question six months later, or a bystander in a community chat forum, when you see others having a good experience, it makes you feel better about the project, too.

People Over Process

Continuing on the previous theme, large development teams rely on process for efficient operation. Whether they use bug tracker workflow management to validate when changes can go into CI or be merged, or smoke tests that run on every pull request, we build up layers of tooling to help developers work through a large number of changes without going mad.

For someone active in the project, this kind of thing provides huge value! But for a newcomer to your project, it’s all very mysterious. As a community software developer, be mindful of newcomers to your project--if their first PR does not pass smoke tests, it is worth taking an extra minute to explain what the tests are, and why they are important, rather than just commenting “CI fail” or “Whitespace issues” without any context. In short, value the person making the contribution more highly than the contribution itself.

Build Relationships

Finally, when a new contributor shows up to your project, you have an opportunity to engage with someone who is using your project, to find out more about how they found it, what they like and dislike about it. That information is golden - direct access for developers to their users is one of the things that separates open source software development from proprietary software development, take advantage of it! And having a conversation has another by-product: for a user who may have been considering your software as the product of a faceless corporation, you are putting a name and face to the project. In short, you are building a relationship.

Think about the first time you turn up in a new school, neighborhood, or company - the thing that makes you feel like you belong is that human connection with someone who, just a few minutes before, was a stranger. This relationship, as small and as nascent as it is, is what will bring this person back, and turn them from a consumer of your project into a participant in your community.

(Image by The McClouds, CC by-SA 2.0)


About the author

Dave Neary is the Field Engagement lead for the Open Source Program Office at Red Hat, communicating the value of open source software development to Red Hat customers ad partners. He has been active in free and open source communities for more than 15 years as a consultant, community manager, trainer and developer. In that time, he has worked on advising companies in finance and telecommunications industry on effective adoption of, and participation in, open source projects.

Read full bio