Are you a beginner to github open source projects ? Stuck on your first contribution ? Then this blog is for you. The first open source contribution has a steep learning curve and it’s perfectly fine to get stuck and feel frustrated. It’s okay for beginners to take their time.
In this article I have described how you can get started with open source on github and in the process shared how I contributed to open source for the first time . I have described my first contribution in great detail, what challenges I faced and how I overcame them. My main intention behind the detailed description is to help you come up with motivation when stuck in a similar challenging situation because due to the steep learning curve of first contribution even small problems can be demotivating enough to make you give up, especially for college students , who are not aware of even basics like software development cycles, git etc. It's gonna be a long blog, so hang tight.
Table of Content:
- Introduction
- Filtering out the Github Project
- Using Issues Tab
- Using explore tab
- How to identify a good open source project ?
- Getting familiar with the project
- My experience
- Feeling of getting stuck
- Tried a new view point on problem
- Challenges faced while getting familiar with kafbat-ui
- Finally working on the assigned issue
- How to push changes to codebase
- Conclusion
Introduction
In our journey of contributing to open source github projects first we will see how to filter out projects which suit our skill set out of the sea of github projects. The advanced search of github is an art of its own. Then we will see criteria for a good open source project for contribution, out of the filtered results we have got. To start working on an issue, it's a good idea to find an issue with the tag “good first issue”. Before working on an issue it’s a good idea to get familiar with the technologies used in the project and do local setup of software. So, the next thing discussed is how you can get familiar with the project. After this I have discussed what are the challenges I faced getting familiar and fixing the issue. After you have figured out the fix for the issue, we will discuss how you can get your changes pushed to the codebase. Alright then, let's begin.
Filtering out the Github Project
In January,2025 after having experience in web development & getting laid off , I tried my hands on open source. I was looking for something to contribute in java using spring boot framework. I couldn’t find any such open source community, just found broken links on websites pointing to such projects. So, in the end I resorted to github. Being a beginner to github search, I struggled to find relevant projects as many of the projects are just personal projects. So filtering out appropriate project was necessary. As being new to github, opensource, makes this a difficult task. Even small looking things can be difficult and demotivating. But, I kept patience and took baby steps without worrying about the end goal for now.
Here are some methods to filter out projects. You can go to this youtube video.
How to find Github Repos to contribute to... (Relevant to you!). I have learnt below methods from this video itself and have added my experience here along with it.
( Keep in mind the interface changes with time, so all the buttons might not be at the place they are shown ):
Using Issues Tab ( which I used ) :
- All the repositories on github have an “issues section” also, where you can see any bugs reported , or features proposed by users. There is an issues tab as shown below. Using the search bar in this issues section you can filter issues related to all the github repositories available in the world.
- Now in the search bar shown below you can filter out issues, using some key-value pairs. The query I used to filter repositories is :
is:open language:java label:"good first issue"
- Here “is:open” filters all issues that are in open state as of now
- Here “language:java” filters all issues which are related to the java language. You can change the java to your required programming language.
- “label:"good first issue"“. All issues have labels assigned to it also. Now this is what helps beginners a lot. Maintainers use this “good first issue” tag to mention that these issues are suited for developers who are new to the project. Such issues are an easy starting point and can help you feel confident.
One word of caution here, I had some issues while entering this query in the search bar, so if you don’t see results
- try pressing the enter button again and again.
- try adding a space at the end of query,
- try removing spaces in between these key- value pairs using delete , put space again and then hit enter. I hope this works for you.
- You can understand further about filter key value pairs from here and here
- I wanted to contribute to something related to Spring boot technology. So then, you can check the number of contributors in each project , number of forks there, star ratings. Anything above 100 forks should work. It's so that the community is big enough that somebody can help you if you are stuck somewhere. Then, I manually went into each search result and tried to find a suitable project. I know it’s kind of a brute force solution, but I couldn’t filter repositories using "number of forks" or either using "spring-boot". And Hence I found meilisearch-java.
Using explore tab:
Click on hamburger icon
Click on Explore tab
Here explore tabs suggests repositories based on your recent activities on github.
A better way is to go to the Trending tab, which has a “language” filter available.
Choose the language you want to and Voila! Filtered. Then you can find an issue with the “good first issue” tag in the project, to find beginner friendly issues.
So, that’s how I found an issue on meilisearch-java and then pinged on issue chat to assign me this issue.
How to identify a good open source project ?
Now that you have found the project , you should further check for some basic standards of the project.
Some basic things to check are:
- Go through the contribution guidelines defined by the project maintainer. You might find it in README.md or CONTRIBUTION.md of the project. Good contribution guidelines are necessary for creating a collaborating environment on open source. So, be on a lookout for that.
- You can see the recently closed issue. Check whether you can see response time to comments is reasonable enough or not. Since, there might not be frequent work going on on issues, so you can avoid that.
Getting familiar with the project
- Now, next comes understanding the codebase. It’s something that has a steep learning curve, not only in open source, but even for contribution to any codebase at job also. A good way to get started is:
- go through the main README.md documentation. Try to understand what technologies are used ( can google it further to understand them more online), what feature does this open source softwares offers to user.
- Then, try to set up a local development environment . Okay, so now what is a local development environment? Basically, whatever open source software you intend to contribute, it would run on some production level hardware. Like if you create web application, then it would be deployed on a server ( like AWS or some other cloud service) or if you want to contribute to a linux or any other operating system, then it runs on end user’s machine, a desktop app deploys on end user’s machine on the top of operating system. So, solving a bug in the production environment is not possible, like you can’t debug a website that is being used by thousands or millions because even a small change can destabilise the whole website and would create problems for thousands of customers. Hence we create a similar setup on our local desktop to reproduce the issue, and fix it without impacting business. I hope this clears the concept. Generally, this setup is mentioned in README.md. Try to follow the process mentioned there and it should work. If stuck somewhere, may google search and stackoverflow with you. Then you can play around with the features and can get used to the software.
- Now, you might think the next step would be to understand the whole codebase, which is rarely the case. A good way to get started is to take an issue , like the “good first issue” we find above and keep understanding the software around it to solve the issue. Keep iterating over codebase in this fashion using issues. You will learn about the codebase and contribute to the project side by side.
My experience
Feeling of getting stuck
I tried the process I mentioned above for meilisearch. But after spending three days, neither I was able to set up the local development environment, nor I got any response to my request to assign me the “good first issue”. That’s the point when self doubt and frustration creeps in. But here is what needs to be understood, you need to have a good temperament as a software developer, it might feel like you are not able to move ahead in even the most basic things and have already spent a whole week finding a good project. But, first issue has a steep learning curve, that’s why even small things become really difficult and frustrating. In day to day software development tasks( not only for this open source contribution ) at times small things take a long time. It doesn’t mean you are an inefficient or incapable developer. I have seen even experienced developers stuck on small things and it’s a part of the job. So just keep patience ,keep learning , keep moving.
Tried a new view point on problem
Of course , after three days I knew this was not gonna work. So, I tried a new angle on the problem. I started finding out another project , so back to square one. But this time I made sure that the community associated with the project is active enough, people are getting responses in a reasonable time. Further they should have more “good first issues”. Hence , I found kafbat-ui . There I asked to assign me an issue. But, still I was working through stack overflow, google searches, on mellisearch local development environment issues. Fortunately, I got the issue (this issue) assigned on the same day at kafbat-ui. I finally felt something is moving forward. So, I put a pause on mellisearch and started working on kafbat-ui issue. Point to be noted here is that, I don’t encourage chop and change, everytime you get stuck somewhere, but if you are stuck somewhere for a reasonably long time and not getting any response for 3-4 days it’s time to look at things from a different perspective. Of course the experience you gained won’t help directly now, but if you don’t repeat mistakes, it will at least guide you where to move next.
Challenges faced while getting familiar with kafbat-ui
Now comes going through README ,& I am not saying the path I chose in next steps is an optimal one or you should do the same. I made mistakes and chose a longer path to analyze the issue (it took me almost a month to analyze this issue).I started to go through README.md piece by piece and worked my way up to solving the issue. ( But, instead I could have just read only essential parts in README like what are the features in the project , how to do local setup and then jump to issue directly and understand the things when required).
I started going through the README.md , since the open source project is a kafka manager, so understanding kafka is a prerequisite. So ,I put a stop here and went to understand kafka. I was able to understand the whole concept flawlessly , but again when I tried to repeat it practically on my machine,found a bug, I remained stuck for 2-3 days ( frustrating, isn’t it? ) , but after downgrading my java version, I was able to get around it. Finally I was able to implement and understand the basic concepts of kafka like broker, producer, consumers, partitions etc.
Then back to README , for getting started I forked the repository and cloned repository to local ( although now I understand I didn’t need to download repository to local , the getting started command already included downloading a docker image, so all I had to do was to run a command). Then to check the features I tried connecting the local kafka broker to my local kafbat-ui . But, again got stuck for 2-3 days figuring out how to connect the two. Finally I asked on the discussion forum of kafbat-ui (here). The prompt response helped me resolve the issue quickly, I understood how important community support is in open source. I got some idea how dockers do networking , added docker to my upskilling bucket list and moved forward.
Next part was about the helm chart. It was related to kubernetes. I was able to understand it superficially. I had already spent a lot of time going through README and my issue didn’t depend on it . So, I left helm charts and the rest of the README for later on and moved to issue.
Finally working on the assigned issue
Before telling further challenges I faced here, let me explain the “good first issue” first, to give you some context. Basically the whole application can run on the top of docker and the project uses docker-environment-variables to give the kafbat-ui app instructions about how to configure itself. In the issue, an error log was coming , indicating that some configuration is failing. Now, I tried to poke the code and search how environment variables are linked to application configuration but couldn’t understand it.So, I tried to go bottom up. I thought maybe this project is using some technology that I am not aware of :
- First I tried to find on the internet whether there exist some way of accessing the environment variable from inside a java spring boot app. No matching result in codebase.
- Then , I tried to understand the build logic in pom.xml and researched about every technology used there. It took 3-4 days. ( Again not an optimal process but nothing else striked me then. ) Unfortunately there was no such technology in the project which was doing this conversion.
Then, I tried to find where the error was coming from in the codebase ( which I should have done earlier, stupid me ..). I tried to trace back the function calls and finally I was able to find the culprit which was converting environment variables to application configuration. There was a Map structure , which was mentioned in application configuration environment Variable List as List , and the same mistake was made in documentation to depict a Map as a List. Hurray!!! …. This solved my first issue , closed the issue. My first open source contribution.
This whole process took around one month.
One month later , the response on mellisearch also came. It said you don’t need to get an issue assigned to you to start working on the issue, the first push request (PR) which solves the issue is taken by the maintainer.
How to push changes to codebase
Unfortunately, my issue fix didn’t need any code changes in the codebase. Otherwise I would have shown how to push your fix to the production codebase. But still here are some pointer
1.You need to understand git first. First of all, git and github are two different things, git is a version control system and github is a place where all open source directories are compiled. Version control system (git) is a software which helps a group of developers to develop software concurrently. When there are a bunch of developers making changes to the codebase concurrently , the challenge is to avoid inconsistency (contradictions). This is where the version control system (git ) comes in and helps.
2.The different stages while making a change in code bases involves: Forking the codebase, cloning this to your local machine, making changes to fix issue, commit changes to personal copy on github, raise a PR request.
3.This article could help you understand how to do this better than I told here and further you may need to do research online git commands.
Conclusion
So, that’s how I made my first open source contribution. I know it’s been a long article, but the first open source contribution is really a complicated process for a total beginner . I hope this blog helps you. Just don’t give up and keep attacking the problems from various angles.
Wishing you your first open source contribution !!
Top comments (1)
Great post showcasing your journey, I must say. Congrats on making your first contribution! :-) 🎉