Let's say you want to contribute to a large Open Source project like React or VSCode: are you supposed to know how the entire codebase works?
Good news, no you don't.
But then, how do you even get started? If you feel overwhelmed and don’t know where to start, you're not the only one. I'm Leonardo, and this video I'll show you how to approach to a large Open Source project.
here below you can find the script of the video
Pick a project
First of all, start small, seriously. If your expectation is to develop the new greatest feature as your very first contribution, chances are you’re definitely overshooting.
Bonus points if you don’t even know the project. The suggestion here is to start with something you’re familiar with, for example a tool or a library you're using in your daily job or in your side projects and the reason is quite simple: onboarding will take way less time since you might already know what to expect or how the project works.
To make sure I don't get misunderstood, I'm not saying you must know everything about the project's internals. At least having a general idea of what the tool does and actually already using it, will make your life way easier, in particular when it comes to evaluating how tricky an issue could be or what kind of features you could suggest and later implement.
If you never used the software you're trying to contribute to, you might end up spending a lot of time just to get started and this can be quite frustrating.
Project setup
Now that you decided what project to contribute to, the next step you might expect is to find an issue to work on. Well, wrong answer. The first thing you should do is to read the contributing guidelines. I know, I know, it's boring, but trust me, it's important.
If you're more into practical stuff and less into theory, then the first step can actually be trying to run the project locally. This might not always be as easy as running npm install and that's why there's usually a section in the contributing guidelines explaining how to do it. Once again, read the docs.
And here, this is one of the easiest ways to contribute to a project: improving the documentation. How? A really common case is that the documentation is either outdated or missing some information. In this case, you can simply open a PR to fix it.
It might not seem like the most exciting contribution, but think about it. If you can spot a problem during the setup process, this will likely also affect other people. So, by either fixing the setup issue or improving the documentation, you're actually helping the project and the community behind it. Your tiny documentation update you're doing today, might be the reason why someone else will be able to contribute to the project tomorrow. This can have such a huge impact!
Follow the rules
But I know you want to write code so let's get into that.
One of the main reasons to pick a project you're familiar with is that since you're already using it, you probably have some ideas about possible improvements or nasty bugs you'd like to see fixed. The time to create an issue has come!
Even if reading the docs is boring, if you haven't checked the contributing guidelines yet it's now time to do it. What could go wrong? Well, we're talking about big projects which are likely receiving dozens of issues every day. The only possible way to handle from the maintainers that is that there are some rules in place, for example there might be a template to follow or at least you should try to provide as much information as possible.
What happens if you do not stick to the rules? Your issue might get closed without even being considered. So, read the docs and follow the rules.
To be clear, it's kind of accetable to close an issue if it doesn't follow the rules. It's just a way to keep the project maintainable in a timely manner.
Can I take the shortcut and create a PR without an issue first? Not necessarily. Some projects have the rule that PRs must be discussed in an issue before being opened. This is to avoid wasting time on PRs that might not go towards the project's goals or that might not be accepted for other reasons.
Again, it's all about not making anyone waste their time, it's sad to have your PR closed after you spent much time working on it, but it's even worse if this could have been easily avoided by simply following the rules.
If you're just fixing a typo in the docs, you can probably skip the issue and open the PR directly, but if you're working on a new feature or a bug fix, it's better to open an issue first.
The codebase
Let's get back to our first question: do I need to know how the entire codebase works?
As we already said, the answer is clearly no. Especially in large codebases, more often than not there isn't a single person knowing everything about the project. It's just too big, so even people working full time on it, might only know only a portion of that.
As a first-time contributor, you can start by trying to get an overall idea on how things work only in the part of the code you're interested in. But, how do you even get there?
After 4 minutes talking about this topic, I can finally mention the label "good first issue". This is a label that is usually applied to issues that are considered a good starting point for new contributors, usually because they do not require a deep knowledge of the codebase and the issue is well explained and scoped. And this is actually what makes an issue a good first issue.
Since at this point you probably have no idea where to look at, the issue description is supposed to guide you through the codebase and explain what you need to know to get started.
If you're still feeling kind of lost, don't get frustrated, reply on the issue to inform you're a new contributor, you'd like to work on that issue and you're in need of some code pointers. Wait, what is a code pointer? In short, you're asking for some hints on where to look at in the codebase to get started and this usually is the name of a function or directly the line of code where you should start.
That's it!
At this point, you have the project running locally, you have an issue to work on and with the code pointer you exactly know where to get started. What's next? Well, time to write some code!
You will need to fork the repo, clone it locally, do your changes in a separate branch and then create your Pull Request. If you're not familiar with this process, here's a video explaining step by step how you can do that with GitHub Desktop, the official GitHub client to work with git.
And with that said, thanks for reading this article and see you next time!
Thanks for reading this article, I hope you found it interesting!
I recently launched my Discord server to talk about Open Source and Web Development, feel free to join: https://discord.gg/bqwyEa6We6
Do you like my content? You might consider subscribing to my YouTube channel! It means a lot to me ❤️
You can find it here:
Feel free to follow me to get notified when new articles are out ;)
Top comments (2)
Excellent article! I agree, looking for "good first issue" tags is wonderful. Also looking at closed PRs around previous "good first issue" or related issues can be helpful as they often contain nice discrete chunks of work and you can see all of the areas of modification in one place.
I remember my first contribution to the cert-manager project. (A large Go project in the kubernetes space). I wrote in the ability to do DNS validations in AWS Route53. Man, I was so proud of that feature... it passed review and got merged in. However I had forgotten to declare the config blocks as a pointer, so everyone who upgraded and DIDN'T have those config values present ended up having a broken cert-manager instance. Not a great thing to have on mission critical infrastructure.
However the team was SO nice and even found a bit of humor in the whole situation. OSS contributions and community have been some of the most fulfilling experiences of my life.
Cheers!
very nice article!! have any recommendation OSS repo that newbie friendly?