Mastodon
//Ris Adams;

Becoming an effective open source maintainer

Cover image for Becoming an effective open source maintainer.

Developing code is not easy. It is a challenge, but it is also a fun thing to do. Maintaining a project, however, is not easy either. It requires a very different skillset and time investment. When I became a maintainer of Selectize, I was able to learn a lot about the project and how to improve it, and I was able to learn so much about how to interact with the community.

Why I became a maintainer

As developers, we all rely heavily on open-source projects and packages. Many of the projects we use are maintained by the community, and we often find ourselves in a situation where we need to make a change to a project. While some projects are sponsored by large companies with dedicated developers, others are maintained by the community, largely by one or two dedicated developers operating in their own time, and without any outside help and financial support.

Specifically, while working on ArchiTECH™, I relied heavily on the Selectize project. When the project was no longer able to be maintained by its original team, I needed to make changes to support my own needs, but I was also able to learn a lot about the project and how to improve it, and I was able to learn so much about how to interact with the community; it seemed selfish to hide the improvements behind a fork, or to find a new solution for ArchiTECH™.

After a few conversations with the prior maintainers, I was able to gain access to help bring the project back to life. Being able to help so many other developers was a great learning experience and I am grateful for the support I received.

Things I learned

Being a maintainer is a lot of thankless work., but it can provide a lot of value and satisfaction. Here are some tricks and tips that I have learned to help me improve my skills, and I hope you can learn from them.

  1. Expect a lot of feedback. Between new issues, pull requests, and other contributions, I expect a lot of feedback. and I’m always learning new things. I try to set aside my mornings to check my Github notifications and prioritize my work so that I can be as responsive as possible, without being too busy or disruptive to my primary work or family.
  2. Most people are wonderful. I’m a very friendly person. I’m always happy to talk to people and help them with their problems. I’m also very open to suggestions and feedback. Most of the interactions you will have with community members are amazing, you can learn a lot from them and they will be very helpful in making your project a success, and make you a better developer.
    • Sometimes people are not so friendly. This can be a huge burden on your mental health, and it can be a real pain to deal with. It is good to help set expectations about what people can expect for your time. Unless maintaining your project is a full-time job, you have every right to ask for patience and support.
  3. Make it easy as possible for newcomers. Your readme file is the first thing that people see when they come to your project. It is a good place to explain what your project is about, and what it is not about. It is also a good place to explain how to use your project.
    • Have a quick start section for users, that not only explains how to install your project but also how to use it. Similarly, have a quick start section for contributors, that explains how to contribute to your project, navigate your codebase, and what the expectations are for issues and pull requests.
  4. Document clearly. Learn to write well, and then learn to edit well. Seriously, it is hard to document well, and it is hard to edit well. These are skills that will skyrocket your success as a maintainer and have the most direct impact on your career. There is no other task you can do that will have such a direct impact on your success.
    • ProTip #1: Read your documentation out loud. It is a good way to learn to write conversationally. Ask yourself if what you have written is phrased in way that you would explain it someone in person, if not try to make it clearer.

    • ProTip #2: Have new contributors test your documentation. If they ffind omissions or errors, corrections make an excellent, easy, and, and valuable pull request!

  5. Encourage pull request reviews. Reviewing code for correctness and possible issues is a great way to get feedback. Ideally have multiple reviews with at least 2-3 people on the project. It is a great way to get good asynchronous feedback.
  6. Automate. Humans are easily distracted fickle beasts with very poor time-management skills. It is a good idea to have a system that will automate as much as you can. It’s less work for the maintainer to do and it helps contributors to be more efficient. You should have at the very least a system for automatic build and tests on each commit and PR. It is an easy way to enforce code quality scanning, dependency management, and other tools using freely available tools such as Github Actions. It will make your life easier to stop focusing on small details so that you can focus on the bigger picture.

Where do we go from here?

If you are a maintainer of a project or a new developer looking to make your project open-source, and you want to learn more about how to improve your skills, I recommend you to learn as much as you can, and practice often. Read through Contribution Guides. They are great resources for all maintainers and will help you learn how to improve your skills. Feel free to take a look at any of my open projects and see if I have a project you can help with. I would love to help you out, and I hope you enjoy your time with me.

§