Some of the best practices that we can follow as maintainers of open-source communities

Some of the best practices that we can follow as maintainers of open-source communities

What does it mean to be a maintainer? I mean not just in the literal sense but what all challenges that we as maintainers face when we talk about managing an open-source community. Are we biased? Do we struggle to put our point across? Are we not able to say ' NO' when we need to? We'd want to make our and our contributor's life easier by putting in place and abiding by, some of the best practices in open-source community management.

Why does open-source matter and why are we talking about it?

Most of the web as we know of today is created on the concept of open source software. Open source software may have a solid backing from an enterprise or it may thrive upon donations and volunteer efforts or a combination of both of these approaches.

With open-source the source code is always openly available for us to use, edit, distribute, etc. When we say open-source we aren't just talking about the availability of source code but also about the community through which it exists, the community collaboration, its ethos and values, community management best practices, etc.

When we speak of being a party to any of the open source projects or initiatives, we also speak of the abundance that these platforms come with like;

  • These platforms reduce the running costs of business operations as we can engage a community of contributors to take care of the minutest of issues. Plus the maintenance costs are almost nil.
  • We have a quick development to market cycle, that gives us an edge over our competitors.
  • We can be assured of the security parameters of the software built on open source projects as there are 'many eyes' to review the code and suggest improvements.
  • If we are a bit hesitant about going big with our project then we can always begin small in an open source platform. Gradually as we build confidence we have the option of scaling up commercially.

What does it mean to be a maintainer of an open source community?

In the early stages of an open source project, maintainers are involved in making decisions pertaining to the project, like what we want and what we do not, making everyday decisions, defining the scope of the project, and how to engage the contributors, etc. As the project grows in popularity, we'll find ourselves spending more time with our contributors and users. As maintainers, we may find ourselves coding less and responding to the queries of the community more.

Maintaining an open source project requires a certain set of skills. The tasks associated are often unexpected and very urgent. These tasks are beyond coding however they are as significant for the success of the project. We can follow a set of best practices to manage an open source community and also to make our lives easier!

1. Documenting, documenting & more documenting!

Writing down what you think and want not just helps you have more clarity but it also supports your community members to have clarity on what is required and expected out of them. Maintaining and working on elaborate documents is one of the most significant things that we as maintainers can do. It goes a long way in bringing success to the project.

If we do not want to write essays, even writing in bullets will make sense rather than not documenting at all. Documentation makes it easier for us to say no to things that do not fit with our ethos. In an open source project, you'd never know who might be using or reading through your project.

Make sure that the documents are updated and delete all the outdated ones regularly.

What can we include in our documents?

  • The vision with which the project began: Writing down what our goals are will support us in making the right decisions. We will remain focused and avoid the 'scope creep' mess while partnering with the other contributors.
  • Clarity about what we expect: We do not want to be police to check others' behaviors or to spoil all the fun!  It could be nerve-wracking to write down rules. However well written and fairly enforced rules can also empower the contributors. They can prevent everyone from being dragged into things they'd not want to get involved in. The contributors of open source projects are spread across geographies. They may not know you and your intentions. Hence communicating clear expectations is not just fair but significant.

2. The dichotomy of when to say 'NO' and when not to!

Having everything documented supports us when we'll need to enforce a strict 'NO'. We'll be able to enforce the rules when needed. Saying 'NO' can be quite intimidating however when we need to we'll have to put our foot down and assert ourselves. These situations can crop up more than expected like someone necessarily getting involved in others' work,  some feature requests that do not match with the scope of the projects, etc.

Okay, for some of us saying a 'NO' can be daunting. Let us see what can we do to make it less intimidating

  • Adopting a proactive approach: If we want to limit the unwanted contributions in the very first place, we'll need to explain the scope of our project and what kind of contributions we accept, and what we do not. If we receive a lot of unwanted contributions, we may ask such contributors to do the homework and then come back. Some of the contributors may outrightly disobey the rules. Here we'll need to stop the conversation and take them through our documentation. Sometimes while saying no, some of the contributors may get hostile. Don't shy away from removing them from the community if they do not collaborate constructively.
  • A friendly flow of conversation: One of our first natural reactions to any of the unwanted contributions could be to quietly ignore or pretend that we didn't see it, rather than saying no. This will not work in the long term. We shouldn't keep the contribution open because we want to be nice and don't want a confrontation. Over time working on unresolved issues will make the project more stressful. Also, ignoring any contributors may send a very negative response to your community. So what can we do?

We can acknowledge the contribution while thanking them for the interest that they've shown, but politely making our point clear of what we accept and what we don't. We can explain to them why their contribution may not fit with our scope of work. You can even share the relevant documentation with them and eventually close the request.

If a contribution isn't good enough for our project, we are under no obligation to accept it. The more often we practice saying 'No', the easier it may get.

3. Involving the community in managing the workload

As maintainers, we'll not need to do everything ourselves. The reason why we work with a community is to engage them to get involved in the everyday workflows of the project.

  • Sharing the responsibilities: If we want to involve the contributors, we should begin by asking around. One of the ways to begin with is to label the issues at different levels to gain visibility. When some contributors make repeated contributions, we can recognize their work and offer them more responsibilities. We can also document how the contributors can gain leadership roles within the community. When we encourage others to own the responsibilities of the work that they are doing, we'll empower them to perform better and, in turn, reduce our workload. We can easily step away from the project and ask others to pitch in, which is okay.
  • Letting contributors create their unique solutions: It may so happen that some of the contributors may have contrasting views about what the open source project at hand can do. Hence we may encourage such members to work on their forks.  Forking projects is not necessarily a bad deed! Copying and working on the fork is one of the plus points of open source projects. Similarly, we can also let users come up with their solutions if we don't have the bandwidth to work on them at the moment. Providing API hooks and customization can support people to come up with their own unique set of solutions.

4. Let machines do what humans shouldn't!

Just like we engage the contributors and users in sharing responsibilities in an open source project, similarly, we can engage machines for tasks where human intervention isn't necessitated.

  • Automating the project: One of the significant methods of bringing automation into our projects is by running tests. Tests can help us as maintainers to review and add contributions quickly. Also, these will empower the contributors. Being responsive is equal to being engaging and gaining engagement.  We can set up automatic tests that may run on all the incoming contributors. At the same time, document how these tests run and what they are about.
  • Using niche tools for everyday workflows: Several tools are available to automate basic workflows, especially if they are repetitive. For example,  Danger will automate code review, Sematic Release can automate the releases, and No Response can automatically close any issue after a certain period. Other than these, for common contributions and bug reports, we can use the Pull Request Templates & Issue Templates available on GitHub. Similarly, we can set up email filters to manage priorities. Further style guides can set standards for project contributions. However, we must also ensure that our standards aren't too complex. We are making rules only to make everybody's lives easier.

At Tooljet we are embedded in the philosophy of open source projects and the contributions that they drive. We believe in actively supporting the best practices in the open source communities. By contributing to the existing open source projects and opening up our own, we seek to keep contributing to the open source movement. Right now, we have about 200+ contributors & 950+ members in our slack communities. We are grateful for over 12500+ stars on GitHub

Ending Note

What value our project provides is the determining factor for the quantity and quality of the contributions we gain. Hence usability and impact are the guiding features of any open source project. If our project can solve many problems of our users and positively impact their lives, we are sure to gain humongous contributions.

Maintaining such popular projects is rewarding.  We as maintainers can grow professionally and personally, something very few others can do. While it may not always be as easy, setting clear boundaries and taking on comfortable responsibilities can help us remain focused, happy and productive.