This guide is meant for people who make open source contributions as part of their work for an employer. Companies and other organizations engaging with open source communities and enabling their employees to work with open source projects is a very direct form of collaboration. This can create a lot of value for all participants, the organization contributing, the open source project receiving the contributions, the people contributing, and the users of the project. But there also are pitfalls which can make contributions difficult and ineffective, cause conflict or let them fail to achieve their desired result.
So how do you interact with a community? How do you make sure you are respecting the needs of all participants, including the needs of your organization? How do you make sure that your participation is valuable?
There are expectations and rules, there is culture and conventions. Not all of this is obvious. You will need to follow organization-internal rules and procedures. That is covered in another guide, the Guide to Outbound Open Source Software. This guide here will focus on the organization-external perspective. To engage with the open source community in a respectful, transparent, and productive way, we call “authentic participation”.
Here we lay out the seven principles of authentic participation:
- Starts Early.
- Puts the Community First.
- Starts With Listening.
- Continues by Participating.
- Has Transparent Motivations.
- Promotes Respectful Behavior.
- Ends Gracefully.
Principle 1: Starts Early.
Engage with the community early in the process of development before things are “done”. Build trust. Incorporate feedback at the founding stages of your contribution. Learn from the community. Think collaboratively. Use consensus in choosing what to build. Engage early and often.
You might be tempted to start by making contributions right away. This is rarely the best approach to establish a good long-lasting relationship with an Open Source project, and it can sometimes lead to unintended consequences. For example, a project may have already started work on a related feature, or previously discussed a feature and decided not to implement it. If you start making contributions without this context, you risk wasting time and effort on a task that is not needed or wanted. Even worse, if no one on the project knows who you are, it might even come across as trying to force through a change that is only relevant to your employer.
You can avoid these unintended consequences by following the first principle: Start Early.
Rather than starting with contributions, start by getting to know the community: how it works, what are its needs, and how it is governed. Engage with the community by joining their preferred discussion channels and talk about the contributions you want to make. Always take a humble and transparent approach. Demonstrate your eagerness to learn and collaborate. Disclose your company affiliation. Build trust with the rest of the community by engaging before you start any work.
Don’t be afraid to show humility. Starting early prioritizes learning and offers respect to the expertise and history of the community. You will find that there is a tremendous wealth of experience in the community and they probably have already thought about what you are going to do. Don’t join projects from the peak of Dunning-Kruger’s “Mount Stupid”.
When you talk about any potential contributions, tell the community what this contribution is important to you. Describe the approach you intend to take and the ideas that you have for implementation. Sharing this information early shows the community that you respect their time and respect the community’s way of working. It shifts organizational contribution from US/ME to WE: Not “I am going to fix things” but “We are going to make something together”.
By following the principle of Starts Early you avoid the bad pattern of someone showing up on behalf of an organization with a significant feature and large pull request, only to find out the receiving project wasn’t interested. That ends up creating bad feeling for everyone involved, where Start Early can help avoid them by both providing the opportunity for community input, and early signal that the project may not be interested in the feature.
Suggested tactics for starting early
- Before you have code, join the discussion, track changes, and listen.
- Ask questions.
- Pick up the easy work. Start contributing to community needs already identified.
- Always be transparent about where you come from, i.e. the organization you are working for.
- When you first join a community, don’t be afraid to acknowledge those who contributed before you.
- Starting early means talking/contributing before things are perfect. Don’t be afraid to show yourself. Use levity and be a human – no one is a widget in a community – but be careful with your language and humor. These people don’t know you yet, and you are probably not that funny anyway. ;)
- This is a geographically diverse and most likely international space. When you start early, listen and be mindful of differences, e.g language differences, racial differences, pay differences.
- Show your work, show your process, show your thinking – before it’s done.
- Be excited, you’re here early, for a reason.
Principle 2: Puts the Community First.
Balance interests and seek alignment. If in doubt put the interests of the community first. This will have the better long-term results. Engage as individual but keep your affiliation and the interests of your organization in mind. Never forget that open source is a collaborative effort and that the collective holds the timeline.
Open Source is about building in communities. Once you start contributing to a project, you become part of the community around it. Open Source is a collaborative effort and thanks to this collaboration results are better than when done in isolation.
Successful open source communities act as a group of peers, where status, position, or affiliation are not important, but the commitment and action of the individual community members is. The saying is “Those who write the code, decide”. This gives you as a contributor a lot of freedom but it also gives you a lot of responsibility. In particular when acting on behalf of an organization you will need to balance the interests, you will need to find alignment. If in doubt, put the community first, though. It will need courage and patience on the side of your organization, but the long-term benefits will outweigh any short-term gains you might get from forcing the agenda of your employer on the project.
Your goal shouldn’t be to try to push as many changes upstream as possible, but to work on the ones that matter. Rather than trying to push your company’s internal roadmap into the project, you should focus on what are the tasks that currently need some help or support, and you can make an impact on. The community you just now joined has some processes and experiences and you should be mindful of those. Use the designated channels and ways of communication, in the end, a community is made of lots of individuals, and the rules are there to ensure a safe environment to foster a successful collaboration. That doesn’t mean that the interests of you and your organization don’t matter, but it means that they are part of the collective interests. If these collective interests are balanced the overall results will exceed what any contributing party would have been able to achieve alone.
“open source is at its most innovative and sustainable when maintained by a community. Rather than a single vendor hoping to hoard the benefits of a comparatively small “pie” for itself, community-led open source development fosters abundance, creating a much bigger “pie” for all, including greater revenue potential for individual vendors.” Source
One important fact of working in a collaborative way is that the collective holds the timeline. Individual interests have an influence, but the ultimate decision lies with the collective. Be mindful of this and act accordingly avoiding to impose or expect any arbitrary timelines, for example pushing for some changes to be merged to meet one of your company’s OKR key results.
Suggested tactics for putting community first
- Act as individual, don’t hide your affiliation, but focus on the contribution not where it’s coming from
- Don’t use your employer, your position in your organization, or other status signals when discussing contributions
- Keep the priorities of your employer in mind, but be prepared for the community having different priorities
- When you need to meet internal targets try to influence the community by taking action in the interest of the community
- Find the small things where you can create value for the community even if it’s not on the immediate agenda of your employer
- Be responsive and considerate, the community is your biggest ally
Principle 3: Starts With Listening.
You don’t want to introduce yourself to a project as somebody who knows it all. Start with listening and learning about the project, its people and its culture. There usually is a lot of documentation and public archives of communication which will give you a very good idea of how the community works. Make use of this opportunity.
When you have been pointed by your company to get into an Open Source Project and you are a new person who wants to contribute to the project the first thing you want to do is get a feeling of how the project is functioning. The first things to do are: read the contributing document, if there is one and if there is no contributing document you could find out how the project works and based on your findings your first contribution could be writing the Contributing document.
Also check the email mailing lists (normally those are published on the project’s site), discussion forums, project repository (repo), and what kind of pull requests and bug/issue reports there are. Some projects use Slack, IRC, Discourse, Discord, Mattermost, etc. channels, so make sure that you subscribe to those. Whichever channel is used, it is good to introduce yourself: who you are, which company you represent, etc. It is good to be transparent that you are in the project on behalf of the company. Once you have introduced yourself, a good practice is to ask for suggestions on where to get started and what kind of contributions are good for newcomers. Remember you are working for a community and it is community needs that come first (see Principle 2).
Some projects have weekly or monthly meetings so if the time zones allow, it is good to participate in those meetings too to get a feeling of the project and the people participating in it.
When you have questions, it is very likely that someone has had the same questions before, so it is again a good practice to search the project’s discussion channels / mailing list emails first to see if your question has already been answered. If your question is a new one, go ahead and ask it. Again, if you think that your question is something that should have the answer in the project’s readme, contributing or other project document, please make sure that you add the info there and make your contribution.
By starting with listening you will learn how the project works, you will also learn about what is not written down, but which is reflected in culture. It allows you and your organization to map the informal network and norms of the project.
And if you are completely new to open source this is a good way to learn how pull requests, forking/branching, review and more work. Open source projects are very welcoming if you approach them respectfully, are willing to listen, and act on what you have learned.
Suggested tactics for starting with listening
- Read the README file
- Read the CONTRIBUTING file
- Look for the main communication channel and have a look at the archives to get an impression how the community communicates
- Go to where the project is. This can include you needing to use communication and source control platforms that you might have opinions about but as a new contributor you will need to do the work to join their community.
- If you have a question, first search issues/pull requests/message boards/FAQs first to see if others have already answered your question. If not, use the proper pathways to raise your question.
- Have a look at closed issues and pull requests to learn how contributions work
- Look for recordings of presentations of the project at conferences to learn more about the project and the people who speak about it
Principle 4: Continues by Participating.
Once you have the basic knowledge about the project, including the community’s processes and communication tools and channels, you can start finding ways to get involved. This means to take small steps to introduce yourself, interact with established contributors and project maintainers, and then eventually find areas where you can contribute and help out.
You should avoid proposing large changes to the project’s code base or documentation as a first act of participation. You need to build out a good relationship and trust with the project’s contributors first, through which you can ensure that your future contributions are in line with the project’s overall mission and goals.
While many open source projects have good documentation and active communication channels to learn from, you might still have questions that you haven’t found the answers for. Asking questions on the mailing list or chat platform is a good way to get in touch with the community. Always make sure that you communicate clearly by sharing background to put your question or comment into context.
If you spent a little bit of time deploying and trying out the project that you have been looking into, you already built up some good knowledge. Even as a newbie you might know the answer to somebody else’s question, or can contribute to help them figuring out a next step in what they are trying to do. Don’t be shy to chime in to the conversation and help somebody else.
Prioritize to do reviews, code or documentation, because that is one of the best ways to learn about the project while performing a task that is always in need of more help and attention.
Don’t be afraid to start participating in discussions if you have input to them, either a comment from your experience or a question that can help taking a conversation forward. It is a good way to show the community that you care about their project and would like to participate in maintaining and developing it further.
Many projects maintain a list of bugs that are marked as ‘low hanging fruit’ or ‘easy to fix’ or something similar to these. Looking into fixing a few of these is another good way to learn and participate at the same time, while also helping the community. Triaging bugs is another good way to help out, if you don’t yet have enough knowledge to fix them.
Starting to get involved in a community’s daily life will help you become part of the team. While you are participating in activities that may not be in direct interest of your employer, helping the community maintain the project always is! This will also build you the path to be able to create a voice for yourself in the community and drive the design and implementation of new features that you and your company need.
Everyone has a different comfort level when it comes to participating in a new community, where you may not know anyone just yet. If speaking up at a meeting feels too intimidating, you can communicate through the mailing list or choose to do code reviews. Always be humble, and communicate clearly. If you let people know that you are new to the project and still learning, others will have a chance to help and guide you through the processes, until you become more established and knowledgable.
Propose changes and show impact. It might not succeed on your first try. Iterate. Keep learning. Don’t be angry if it feels that you are ignored or a suggestion is rejected. This can happen. Motivations differ. Don’t make demands. This will burn up your credibility.
Suggested tactics for participating
- If there is a community meeting, you can introduce yourself to the community and even ask if there is an area where they need help
- You can participate in discussions on the mailing list or chat platform, both asking and answering questions
- Do code and documentation reviews, that is an area where every community needs help at all times
- Triage bugs or look for simpler issues to fix
Principle 5: Has Transparent Motivations.
Without a shared understanding of the motivations, it’s impossible to resolve differences of opinion effectively. No hidden motives.
Your work on the projects should be transparent. Transparency has many different aspects an dimensions that we will try to showcase here.
You should be transparent with the rest on the community about your level of commitment with this project: from working only on issues that overlap with your company’s interests, to help out in anything the project needs, or anything in between; from doing a one-off fix to working towards long-term maintainership of some code. All the options are valid and there is not right or wrong answer.
It is important to be transparent about the reason why you are working on the tasks you pick. Sharing as much context as you can is useful for the rest of the community to better gauge the importance of the work and why it should be included in the project. This is not about revealing company strategies, but sharing and explaining why is this particular piece of work needed and interesting.
We have multiple hats when interacting with communities: our company’s or our own. It is important to differentiate and be explicit about which virtual persona you are in each moment. For example, when committing changes or writing emails, use the corporate or the personal email accordingly (more info).
You also most probably can’t speak officially for your organization, but some people will still perceive you as speaker of your organization. Handle that with care. Don’t play political games, this will fail.
Some companies will have the expectation that they can steer an open source project, because they have money or status or customers. Some companies will try to impose a hidden agenda on a project. This is not how open source works. The currency is active contribution for the benefit of the project. It’s ok to influence a project, and everybody will understand that a company is not contributing for pure idealistic motives. But this is done by sending individuals to the project who are doing valuable work. As an employee you are one of these individuals. So you will need to balance this and be transparent about your motivations.
Suggested tactics for having transparent motivations
- Commit with your organization’s email address when you are working on behalf of your organization
- Put your affiliation on GitHub
- Be conscious of which hat you are wearing at any given moment
- Make it explicit in communication from which perspective you are speaking when recipients might not have this context
- Be transparent when motivations or affiliations change
- Be careful with using background channels. This can disrupt project communication because the project doesn’t have the context.
Principle 6: Promotes Respectful Behavior.
Participants agree to adhere to community-established codes of conduct. Organizations commit to holding their participants accountable for their behavior.
Open Source projects are made by people, with people, for people. It’s easy to forget that the on-line avatars are real people. You should always remain respectful and follow the defined rules of engagement by the community.
Projects and communities often have a Code of Conduct, it is a pledge from the community leadership towards the community that no abusive behavior will be tolerated. Take a moment to read and understand them. You need to follow this the same way you need to follow your internal employee handbook.
Failing to follow such guidelines always has consequences for both your reputation but also the your company’s. It’s on everyone’s interest (your and your company) that you always engage in a respectful manner. Your company will take any infringement of open source projects’ code of conducts as if they were infringements of the internal employee handbook.
But it is not only about code of conducts, each community has their preferred way of communication and way of engage in discussions, please make sure to understand how the communities you are part of prefer to be engaged and follow their ways.
Also be aware that open source communities often have people from very diverse backgrounds, coming from different cultures, speaking different languages. This can be hard to notice, understand and handle, especially when using communication channels such as email or bug reports, which don’t convey much context. It can be helpful to think of that in the light of Postel’s law: “Be conservative in what you do, be liberal in what you accept from others.”
Suggested tactics for enforcing respectful behavior
- Read the project’s Code of Conduct and follow it.
- Don’t assume bad intent when it just could be a misunderstanding
- Don’t write emails when angry
Principle 7: Ends Gracefully.
No sudden withdrawal of resources without notification and an exit plan. Clear documentation that would allow the community to pick up projects when a company decides to withdraw support.
People remember how we leave a room. Our open source endings are a stepping stone to how we enter our next space, whether we return to the same room or enter a new one. Too often well-meaning open source contributors will just disappear, leaving silence and questions in their wake.
Your endings are just as important as any other juncture in the open source journey. How you choose to close it all out should bring to bear all the principles we’ve been discussing to life.
See principles 4 and 5 especially. Be transparent and be respectful. At the onset of engagement, we suggest you share the expected commitment and involvement in the project. At the closure, summarize and share the wrap up. Share where things have gone because no collaboration is too short, as long as it’s well defined upfront. And continually defined ongoing.
Be respectful and mindful that things change. Priorities change, or unexpected things happen, it’s fine. Sharing at the earliest possible point in time with the community is crucial. This is true for premature ending and for unexpected extensions.
Especially if you have taken over responsibility, for example by acting as a maintainer of some code, it’s crucial to step down gracefully, be transparent, and pass the baton to the next person.
Suggested tactics for ending gracefully
- Tell the project when you are not able to contribute anymore.
- If you are a maintainer and can’t continue in this role, find a successor and then step down.
This guide is based on the Principles of authentic participation which were created and discussed at Sustain 2020. Thanks to Justin W. Flory for facilitating this process.
Contributors to this guide (in alphabetical order):