Guides

Employee Open Source Engagement

This guide is for people who are making open source contributions as part of their work for their employer.

Working directly with an open source project can be a great way to create value for everyone. Some of the people who can benefit are: you, your employer, the open source project, and users of the project. Before you start to interact with an open source project you should consider some of the challenges as well as the benefits. This will help you to be successful and avoid problems like conflict or failure.

This guide will help you to understand how to interact with a community, how to make sure you are respecting the needs of all participants, and how to make sure that your participation is valuable.

Note: As you are working on behalf of your employer you will already have some rules that they expect you to follow. We will not cover that in this guide, but you can read our other guide for more information - Guide to Outbound Open Source Software.

In every project there are expectations and rules, there are culture and conventions. It can take time to become aware of what these are, as they may not be obvious immediately. We recommend that you engage with open source communities in a respectful, transparent, and productive way. We call this Authentic Participation.

7 Principles of Authentic Participation

Principle 1: Start 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 its needs are, 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.

Remain humble. When you start early, you prioritize learning and offer 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 the ideas that you arrived to collaborate on. Watch out, you might be at the peak of Dunning-Kruger’s “Mount Stupid”!.

When you talk about any potential contributions, tell the community why 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 “me” to “we”: Not “I am going to fix things” but “We are going to make something together”.

By following the principle of Start 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 providing the opportunity for community input and getting an early signal of whether the project is interested in the feature or not.

Tips for starting early

Principle 2: Put the Community First.

Balance the interests of everyone and seek alignment. If you are not sure, 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 its community. Open Source is a collaborative effort and gives better results than working in isolation.

Successful open source communities act as a group of peers, where the commitment and actions of the individual community members is more important than their status, position, or affiliation. 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 you act on behalf of an organization you will need to balance the interests of everyone involved and look for alignment. If in doubt, put the community first. You will need to advocate in your organization for them to support this approach with courage and patience. 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 should be to work on the changes that matter, not to push as many changes upstream as possible. Don’t push your company’s internal roadmap into the project. Focus on understanding which tasks need some help and contribute to the ones you can make an impact on.

The community you just joined has existing processes and history that you need to be aware of. Use the designated channels and ways of communicating. A community is made of lots of individuals and the rules are there to ensure a safe environment for 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 employer’s deadlines.

Tips for putting community first

Principle 3: Start With Listening.

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. Don’t introduce yourself to a project as somebody who knows it all.

When your company asks you to get into an open source project that is new to you, you should take time to understand how the project functions. Read the contributing document if there is one (or if there is no contributing document you can find out how the project works and create a Contributing document as your first contribution to the community).

Check the mailing lists (normally those are published on the project’s site), discussion forums, and project repository (repo). Get familiar with the pull requests and bug/issue reports on the repo. Some projects use communication channels like Slack, IRC, Discourse, Discord, Mattermost, etc. which you should subscribe to. Introduce yourself: who you are, which company you represent, etc. Be transparent that you are in the project on behalf of your employer. 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 document or other project document, 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 and what 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.

Tips for starting with listening

Principle 4: Continue by Participating.

After you have gained some basic knowledge about the project, the community’s processes, communication tools, and channels you can start getting involved. You can take small steps to introduce yourself, interact with established contributors and project maintainers, and find places you can contribute and help.

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. This will help you to align your future contributions 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 information so that your question or comment has the necessary context.

If you have spent a little bit of time deploying and trying out the project you will already have 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 afraid to add to the conversation and help somebody else.

Prioritize giving reviews on code or documentation. People value this activity and it is a good way to learn about the project.

Don’t be afraid to participate in discussions if you have helpful information to share. Sharing your experience or asking a clarifying question can help move the conversation forward. It is also 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. Looking into fixing a few of these is another good way to learn and participate in helping the community. Triaging bugs is another good way to help out if you don’t yet have enough knowledge to fix them.

Getting involved in a community’s daily life will help you become part of the team. It’s important to participate in activities even if they may not seem to be in the direct interest of your employer. Helping the community maintain the project is actually in everyone’s interest, including your employer! You will also create a voice for yourself in the community that gives your the opportunity to 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 they 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. You might not succeed on your first try. Iterate. Keep learning. Don’t be angry if it seems that you are being ignored or a suggestion is rejected. This can happen. Motivations differ. Don’t make demands. This will burn up your credibility.

Tips for for participating

Principle 5: Have Transparent Motivations.

Without a shared understanding of the motivations, it’s impossible to resolve differences of opinion effectively. Don’t hide your motives.

Your work on the project should be transparent. Transparency has many different aspects an dimensions that we will explain here.

You should be transparent with the rest on the community about your level of commitment with this project. If you can only work on issues that overlap with your company’s interests it is better to be up front about it. If you can help out with anything the project needs, tell them! Perhaps you can do a one-off fix, or maybe you want to work 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. Share as much context as you can so the rest of the community can gauge the importance of the work and why it should be included in the project. This is not about revealing company strategies, its about sharing and explaining why this particular piece of work is needed.

We wear more than one hat when interacting with communities, for example, our company’s or our own. It is important to differentiate and be explicit about which hat you are wearing in each moment. For example, when committing changes or writing emails, use the corporate or the personal email accordingly (more info).

You may not be empowered to speak officially for your organization, but some people will still perceive you as speaker for 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.

Tips for demonstrating transparent motivations

Principle 6: Promote Respectful Behavior.

Learn and follow the community-established codes of conduct. Your organization should commit to holding you accountable for your behavior in open source spaces.

Open Source projects are made by people, with people, for people. It’s easy to forget that the online 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.

If you do not follow the guidelines there will be consequences for both your reputation and your company’s. It’s in everyone’s interest 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.

In addition to codes of conduct each community has its preferred way of communication and ways of engaging in discussion. Take time to understand how each community prefers to be engaged and follow their ways.

Be aware that open source communities often have people from very diverse backgrounds who come from different cultures and speak different languages. This can be hard to notice when using written communication channels which don’t contain much context. Postel’s law is a useful guide: “Be conservative in what you do, be liberal in what you accept from others”.

Tips for promoting respectful behavior

Principle 7: End Gracefully.

Don’t withdraw resources suddenly. Instead, give proper notification and share an exit plan. Provide clear documentation that will allow the community to pick up projects when your company decides to withdraw its support.

People remember how you leave a project. Your open source endings influence how you enter your next project, whether you return to the same project or enter a new one. It can be disruptive when well-meaning open source contributors just disappear, leaving silence and questions behind them.

Your endings are just as important as any other moment in the open source journey. When you leave a project it is an opportunity to practise all the principles we’ve been discussing.

Principles 4 and 5 are especially relevant. Be transparent and be respectful. When you join a project, we recommend that you share the expected commitment and involvement in the project. When you leave, you should summarize and share your exit plan. Explain how you are finishing any work in progress, and where you have documented any handover information. No collaboration is too short, but it must be done properly.

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.

If you took over responsibility as a maintainer of some code, or another important role, it’s crucial to step down gracefully, be transparent, and pass the baton to the next person.

Tips for for ending gracefully

Credits

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):