If you have never contributed to open source, Hacktoberfest is the perfect chance for you.
There are plenty of guides for beginners. This is a guide for those developers with some industry experience - but no open source experience - who have a day job and other obligations.
The goal of this guide is to optimize your time as first time contributor and let you focus on the fun part: coding and collaborating with other people on open source projects.
Contributing to open source doesn't always benefit from all the organization of labor and the structure that you have at work. You can easily waste a lot of time to find the right projects or to setup your local environment or even waiting for a review of your PR that never comes.
This can be very frustrating and make you give up altogether. It doesn't have to be like that. I hope this guide will help you to make the best out of the Hacktoberfest.
This guide will refer to GitHub projects only, but with few modifications you can use it to contribute to projects on GitLab.
Step 1: register to the event
Step 2: find the right projects
Step 3: evaluate a project
Step 4: start contributing
Final considerations
Step 1: register to the event
Step 2: Find the right projects
Discord
If you joined the discord Hacktoberfest server you can find some projects here.
The good thing of finding a project through discord is that you can communicate directly with the project maintainer.
To search for a project written in your favorite language just use the bar at the top right of the screen:
GitHub
I find the GitHub issue tracker very helpful. When you visit this page you will probably find only the issues you created.
This is because the default filters are as follows:
is:open is:issue author:yourgithubusername archived:false
Let's modify the filters to get more appropriate results.
First of all you want to get rid of the author filter.
This is more like it. But the list of issues is still too broad and not so much use.
Now let's say I want to find the Hacktoberfest issues that require as language Kotlin:
The filters that we've applied now look like this:
is:open is:issue archived:false label:hacktoberfest language:kotlin
By default the result are sorted by newest issue. You can change the order by clicking on the Sort dropdown menu. This is a particular that will be more important in the next section of the guide: evaluate a project.
Step 3: evaluate a project
Now that we have a list of possible results, let's see some strategies to find the best project to work on in the least amount of time.
If you found project through GitHub, before visiting every single repo/issue that might have caught your attention there are two important considerations:
1) the programming language might not be a sufficient filter criteria. Different languages can be used by very different frameworks/platform/etc. E.g. A Kotlin Developer might not have extensive experience with Android development. If you found your project through Discord, you probably had the chance to do your own filtering. But if you found your projects on GitHub, sometimes you can get this information directly from the list of issues, by hovering over the repo name:
2) the sorting criteria is very important. You want to have the newest or most recently updated issues. If the issue is new or has been updated recently it means that the repository maintainer is active and/or has interest to find people to fix the issue. This can speed up the review process and make it so, that your PR is more likely to be accepted in time.
Now that we have clarified these two aspects, let's talk about what to look for in the repository itself and how to evaluate the issue.
What to look for in the repository
Documentation
Before being a contributor you'll be a user. A good project has to have some basic user documentation. In smaller projects it's usually in the README.md file, but some projects automatically build the docs from the source, so you might have to visit another website to get more details.
This is the minimum requirement for you even consider this project. You have to be able to run this project on your local environment to be able to test your changes.
When was the last commit
If you got this project from GitHub and followed the relative section you probably don't need this. Checking for the date of the last commit, gives you an idea on if the project is still "alive" and how active are the maintainers.
Domain and complexity
There are repositories that have active maintainers and are well documented, however it can require some time to understand the domain logic (like what's this project about) and tackle the complexity (the repository has multiple independent packages, the project has a lot of features, etc.). The fact that this requires you to do some reading shouldn't discourage you from contributing. However if you decide to contribute to a more complex project consider this 3 things:
1) How interested are you in the domain? You have more chances to be successful if you don't feel reading the documentation like a burden.
2) How many issues in the same project can you start contributing to? Even if you're really interested, you have to consider that all that reading will require time. At some point you will want to get started coding. If there are no issues for beginners (usually labeled as low-hanging-fruit, good-first-issue, up-for-grabs, etc.) you risk spending too much time on just one issue, when you could work on smaller projects. It could be still worth your time, if you think you want to continue to contribute long term to this project.
3) How helpful are the maintainers toward beginners? If you start with a complex project, you will probably need to ask questions and clarify things that maintainers and experienced contributors take for granted. Check how issues are explained (more details in the next section) and how maintainers and other contributors answer to questions. Do they give detailed explanation (like exact names of the classes/functions/packages), provide links, refer to the documentations, etc.? Or do newbies often have to ask extra questions because the answer was not accurate enough? These aspects might influence your decision, as you have limited time.
How to understand if the issue is right for you
Ideally by looking at the issue and source code you should be able to have an idea of what's the issue about and vague strategy on how to solve or at least where to start from when looking for a solution.
When looking at an issue make sure to look at the comments as well. Are there already other users that requested to work on it? If yes, you want to skip this issue it doesn't make sense to have two people opening PRs on the same issue.
If the issue is a feature request
The issue should have clearly defined expectations, possibly provide example(s) of expected outcomes and the name of the class/function/package/file to modify.
If adding this feature will affect other functionalities in a not straightforward way this should be also be accurately described in the issue.
If the issue is a bug
The issue should describe the problematic behavior and what the ideal behavior should look like. Moreover there should be a description as accurate as possible on how to reproduce the bug.
If the issue is an enhancement
The scope shouldn't be too broad or vague. E.g. "Make the application more performant" is a bad scope. There are many ways to do that and this kind of scope invites to a discussion which might end with no decision and no PR on your side.
Step 4: start contributing
When you finally found an issue to work on, make sure to comment it and make the maintainer aware of the fact that you want to work on it.
Read the guidelines to contribute to the project. They are usually in the README.md or CONTRIBUTING.md. If you don't find much information about how to contribute to a specific project, you can follow this list:
1) Fork the project. You will find the "Fork" button at the top right corner of the main project page:
The fork is a copy of the project in your account. You will create your PR from this. If the guidelines require you to checkout from a branch that is not main, make sure to import other branches while forking. Keep in mind that the fork, by default, is out of sync with the relative branch of the original project. If some other pull requests get merged before you're done with yours you will have to sync with the original project and rebase your branch before opening your PR.
You can also automatically sync.
2) Setup your local environment. You should be able to build and run the project locally. Run the tests and see if they are failing. If you have trouble with the setup and there is no information that can help you in the documentation you should probably stop here and look for another project/issue.
3) You probably know this from your work, but in case it needs to be repeated, give your branch a significant recognizable name that points to the issue you're working on.
4) This is also general good advice (but it's even more important in a open source project): write meaningful commit messages. Amend commits if you realized that the message is not good enough. If there is no specification on how to write a good commit message in the contribution guidelines, a good rule is to the name of the branch or issue you're working on at the beginning of the message. E.g. for branch prevent_committing_when_no_changes, a good commit message would be [prevent committing when no changes] added getCommandOutput function. This will make it easier to search the commit history in the future.
5) Testing while coding should give you an immediate feedback if you're going in a right direction. But don't forget to test at the end, to make sure you haven't overseen anything.
6) Write documentation for your code. A good rule of thumb is to follow the documentation style that is already present in the project.
7) Before submitting your PR be your first reviewer. Go once again through your final solution. Read again the issue to make sure that you understood correctly the specifications and didn't miss anything.
8) After submitting the PR if you receive a request from a maintainer try to discuss in a constructive way and don't be defensive about your code (after all we all make mistakes!). Keep in mind that the maintainer is the "architect" of the project and has more knowledge about it.
8) Not being defensive doesn't mean that you can't voice your opinion. Offer your opinion in terms of suggestion and be ready to take for as an answer.
Final considerations
Quantity over quality?
From what discussed above one might think that this guide pushes you to prefer quantity over quality. To successfully participate to the Hacktoberfest you will need 4 PRs merged until the end of October. You might find it rewarding contributing to open source even if you don't achieve this goal. From experience though I found out that having multiple PRs merged in open source projects has given me the confidence to explore more complex projects and I think to become a regular contributor.
I hope this guide helps you in this way.
Maintainers
While contributing keep in mind that maintainers might be "busy developers" too. Writing good documentation, writing good issues and in general maintaining the project takes a considerable amount of time. It's just amazing that people do this for free in their free time. Often maintainers will thank you for the contribution, but you should be thankful as well. As developers we use open source software every day. It is what allows us to build our applications, to learn, to grow, to find new solutions, to innovate. And now you are a part of this!
That's it for this guide!
Happy coding!
Top comments (0)