Discovering Small GitHub Projects for Contributing to FOSS

Did you know there are more than 60k small FOSS projects on GitHub most likely open to contributions? Have you ever thought about contributing to them? If not, then you should. This guide is about helping the reader identify these projects on GitHub. The guide is meant to encourage both new and experienced contributors to find software that have a small impact and contribute to them in any way.

There are existing sites like Up For Grabs and First Timers Only that use crowdsourcing as a way to add & find projects and issues to contribute to but there's a big chance that authors of small projects may not be well represented in this list (marketing projects takes a lot of effort), or even worse you are missing out to work on some interesting hidden gems.

What this guide covers?

  • Understanding the importance of contributing to small projects.
  • How to search projects on GitHub effectively.

What it doesn't cover?

  • How to contribute to FOSS, this guide is only about finding small projects & their impact on the FOSS ecosystem. There are thousands of guides on how to contribute to open-source projects on the internet, the things taught in those guides apply to projects of all sizes.
  • Finding small projects on other platforms like GitLab, Self-hosted Git instances, etc.

Why contribute to small projects?

You can make a significant impact

  • Due to less traffic (or activity) on small projects, your contributions are more likely to be noticed and appreciated.
  • It's comparatively easier to get started on small projects because of less codebase and complexity, which ultimately lowers your overwhelmness to get started.

This is the "Real" FOSS that needs your help

  • Small FOSS is the real FOSS that needs your help. They are not backed by big companies and are not as popular as big projects. They are the ones that require your help the most.

Smaller Fuck Around & Find Out domain

  • Large FOSS projects that are maintained by a community usually have a set of docs to get started. Conversely, small projects may not have those guides.
  • This is a golden opportunity for folks trying to learn by doing. Throw yourself in this clueless, unknown codebase, and see if you find and learn new things. Sure you can do this with big projects as well but hey, the more no. of contributors, the more no. of chances of code patterns plus with a small impact understanding small codebases will be easier and less time-consuming and eventually more rewarding.

You chance for being an early adopter

  • You never know what projects on github might get some traction over the years. If you participate in contributing to small FOSS consistently, it's possible that you might eventually become one of the maintainers.
  • Not just that, it's possible that the project converts into a product or gets used by another big projects.

How to find small projects on GitHub?

We now look at how to use GitHub search effectively to hunt small projects. Let's understand the criteria with which we will filter out these "small projects".

Base Search Criteria

We combine a bunch of search prefixes to build the following criteria:

template:false archived:false fork:false stars:100..500 forks:>=3 is:public topics:>=3 license:0bsd license:mit license:apache-2.0 license:gpl license:MPL-2.0 license:Unlicense license:AGPL-3.0 license:WTFPL license:CC

alt text

Judging the criteria to filter small projects

  • stars:100..500
    • At first glance, filtering by stars may not be a good idea since they can possibly be bought nowadays, but it's a good starting point for us. Projects sitting in this category have some traction and are not completely unknown to the internet but they most likely lack marketing.
    • Reaching this milestone with the number of stars is a sign that the maintainer/author may be serious about the project and is willing to maintain it for the long run. Hence, open for contributions.
  • archived:false
    • Avoid projects where the author has given up on the project or the maintainers no longer wish to continue the development.
  • forks:>=3
    • A project with at least 3 forks is a good sign that the project is being used by others. You can make this criteria more strict by increasing the number of forks.
  • template:false
    • Very few projects qualify as a template, so we exclude them.
  • topics:>=3
    • An author willing to add topics to their project is a good sign that they are serious about making their project visible to the internet. Topics are a great way to categorize your project and make it discoverable.
  • fork:false
    • Avoid duplicate copies of the same project. This works in conjugation with forks>=3 filter, we need to only find the main repositories, not their forks.
    • This has a side effect of excluding forks that are now well maintained & supported by the community. But that doesn't matter in the long run, since the users of that niche project are most likely already aware of the fork. It's also possible that the author of the original project lists the fork in their README.
  • license:0bsd license:mit license:apache-2.0 license:gpl license:MPL-2.0 license:Unlicense license:AGPL-3.0 license:WTFPL license:CC
    • A presence of a license is a very small sign that a project is serious about being open-source. It's a good idea to filter out projects that don't have a license. We have included the most popular licenses here, you can add more if you want. The full license keyword list is available in github docs

How to apply and use the filter query?

GitHub is kind enough to provide us with a "Saved Searches" feature. You can save the filter query as a saved search and apply it whenever you want to find small projects. Let's see how to do that.

Step 1: Search for the filter query

Head over to GitHub's search page and copy-paste our filtering criteria in the search bar and hit enter.

template:false archived:false fork:false stars:100..500 forks:>=3 is:public topics:>=3 license:0bsd license:mit license:apache-2.0 license:gpl license:MPL-2.0 license:Unlicense license:AGPL-3.0 license:WTFPL license:CC
search github with small foss criteria

Click the "Create save search" button to save the search. You can name the search anything you like. We recommend naming it something like "small-foss". Avoid using spaces in the name.

save github search

Once you have saved the search, you can use it anytime by referencing it via saved:<search-name> in the search bar.

use saved github search

As visible from the above UI, you can also choose to edit this search by clicking on "Manage saved searches" anytime.

Step 4: Customize & Combine the search

You can combine other filters with saved searches as well. For example, to find small FOSS Python projects, you can use the following filter query:

saved:small-foss language:python

# or combine multiple languages

saved:small-foss language:C++ language:Java
customize saved github search

Step 5: Sort by recently updated

You can sort the search results by "Recently updated" to find the most active projects in this new filtered search. We could do this by adding pushed>=YYYY-MM-DD to the filter query but that would require us to update the date every time we want to use the search. Sorting by "Recently updated" is a better option.

Sort by recently updated

Small projects have high chances of being abandoned, so it's a good idea to sort by "Recently updated" to find the most active projects.

Note that we have solely relied on GitHub's documentation to build this filter query. We recommend the reader to read the docs to modify the query as per their needs.

What's missing?

  • There's no way to tell if the project has a valid description or not. You can however search for a query inside the description to filter out projects. A missing description is a sign that the author may not be serious about the project.
  • We didn't cover filtering projects based on how many open issues they have. Unfortunately there's no direct filter that will help us know whether issues exist on a repository. Although GitHub offers us 2 prefixes to look for good-first-issues and help-wanted-issues. 
    saved:small-foss good-first-issues:>1 help-wanted-issues:>1

FAQs

What if I don't trust the projects I find?

  • You can always check the project's README, CONTRIBUTING.md, and the issues to get a better understanding of the project and its maintainers.
  • Look for authors on external platforms like LinkedIn, Twitter, etc, and see if they actively talking about the project.
  • In rare cases its also possible that the authors set-up a blog, newsletter or a YouTube channel to talk about the project. This is an opportunity for you to understand the author's vision and the project's future.

What if my PRs are not getting merged?

  • If your PRs are not getting merged, don't worry. You can always ask for feedback and improve your PRs.
  • In the real world, not all PRs will get merged. That's not new and applies to all projects, big or small.
  • Having said that, it's a good idea to move on to another project as soon as you feel you can't contribute anymore. There are plenty of projects out there that need your help.
  • Lastly, if the project is not active, you can always fork it and maintain it yourself :)

What if there are no open issues on these small projects?

Here's your chance to do a lot of things.

  • Install and run the project, find potholes in that process, open issue.
  • Look for bugs in the code, open issue.
  • Run a test suite if it's available, open issue if it fails.
  • Add tests if they are missing, open PR.
  • README looks outdated? Open PR and improve the documentation. Avoid fixing typos, they are not worth the Maintainer's time, unless of course, the project in itself is documentation.
  • There's no CI/CD pipeline? Open a PR with a GitHub Actions workflow.
  • The project is not following best practices? Open the issue and discuss.
  • Lastly, become an enabler for the project. Evangelize the project on social media, write a blog post, etc.

This wiki is maintained by u/BhupeshV