I found a bug in an open source project - What to do next?

Practical advise for getting issues with open source projects solved

If you are working with open source dependencies in your projects it’s very likely you will encounter some type of issue or feature requests. In the last few years of working as software developer I got in touch with many open source communities of different shapes and sizes. I talked to a lot of people who say they don’t really know how get started with open source.

Let’s walk through of a typical journey for your first interaction with open source. In this example we will talk about a bug you discovered in an open source dependency in your project. If you want to add a feature to the steps are pretty similar.

Investigate the bug

You really need to have a close look at your problem to determine the next steps. At first, I try to isolate the problem. If you think one of your dependencies is the problem you need to break it down and get a good understanding what the real problem is.

Identify the right project

Your project is most likely compromised of many open source dependencies. You must try to isolate the problem and make sure you find the right project to report and fix your bug.

Check new versions

If you have the right project you should check if there is a new version available and test it if available. You should always keep the versions up-to-date and fix the problem in the latest version if possible. Also, you might be able to try versions that are in development just by checking out the development branch from GitHub. Package managers like npm or pip usually have a feature for adding dependencies from git.

Create minimal reproduction

If a new version does not fix the problem you should start your reporting and fixing journey by creating a minimal reproduction project for this problem. Typically, you start by creating a new project and just add the dependency in question. Then you should add the minimum code required to see and understand your problem. This makes it a lot easier for you and others to understand and test the problem with the dependency.

Report the bug properly

With the minimal reproduction project you can now report the bug precisely. You should provide all the information you can, to help the maintainers to understand and fix the problem.

Try to find a fix yourself

If you find any issues, projects tend to love to get them reported with possible fixes as a pull request. After your investigation you might have an idea what goes wrong in the dependency. Don’t be afraid. Have a look at the code and try making some changes. You might find a solution yourself pretty quickly. You can also test it very easily with your minimal reproduction project and your actual project. This helps a lot with submitting the patch and explaining why it’s needed. If you are struggling to get started with fixing the dependency you can ask in your submitted issue for ideas and help to get started.

Be patient and respectful

Once you submitted an issue or pull request just be patient. You cannot expect the maintainers to respond quickly. Everybody in open source works on their own terms and schedule. Some maintainers have very limited timed and only work on open source in their free time. Keep that in mind if you are eagerly waiting for a response and always be respectful in your communication.

Stay with the community

It’s good to stay around if you care about the project and not only appear if you have issues you need help with.

Participate in the community

Feel free to take part in the communities you care about on GitHub, Slack, Stackoverflow etc.

You can contribute in many ways not just working on code and issues. It’s also important to help users by answering questions or improving the documentation.

Keep your dependencies up to date

It’s a good practice to regularly check your dependencies for new versions and update them. This will help you to avoid debugging problems that are already fixed in newer versions and improves overall security and stability of your project.