top of page
  • Writer's pictureGal Cohen

Open Source Contribution 101

In this post, I will illustrate the way I normally contribute to open source projects.

I will get technical quite fast, prerequisites for understanding this post is knowing Git version control (and GitHub) to some extent (forks, branches, PRs).

Where to start

Resolving an issue

After selecting the project you like contributing to (you can look in if you don't have one yet), you can pick an Issue from the Issues list under the project repository:

The list illustrates all the work/bugs/feature requests currently the project has. Normally the project maintainers would control the list and prioritize the work. In the issue itself, you can see if somebody is already assigned to it.

Creating a new issue

My personal flavor is not creating an issue before you know the solution / have it in your reach. Creating issues without taking full responsibility creates a backlog for project maintainers, and it creates a mess. All the issues I ever resolved by myself were fixed before I created the issue.

Every project has its own rules about creating new issues/contributing for instance attaching a full log output, and how to reproduce the issue, for example, this guideline or this one.

It is recommended to follow an existing issue (resolved/in progress) and understanding how things went during the timeline (communications, review, feedback, etc..) before starting to deal with a new issue.

Getting some help

Big projects have big communities backing them up. Every community has its own way of communicating. You can search in google for "<project name> users group", and you will get it. For instance Django users or celery-users.

This is the place for getting help about contributing to the specific project, and participants are normally both users and maintainers/contributors.

Showing active participation in the user's group will create more confidence in you by the community. Asking for help is a sign of strength.

Starting the work

Try putting yourself in the shoes of a long-term maintainer, that needs to take your new code and publish it to the world. He/she doesn't know you or your capabilities/background, this means that your work is in doubt unless proved otherwise.

In order to get to the point where maintainers trust you, it's better you have confidence yourself with the solution you are introducing (will get to there soon).

"MVPing" the problem you are trying to solve

Create a very small project, normally it would be a few lines of code, and reproduce the problem without any business logic. This will let you show the maintainers what you are talking about, and will set a clear table for you to make the fix.

Create a fork out of the original GitHub repo

Since this is probably the first time you are doing this, you will not have any permissions to the project's repo, meaning you can not create any new branches in it.

Once you create the fork, you can "import" the project as an external dependency (using your forked code in your small MVP project), instead of the original project. For instance, in Python this is how you can import a module from Git repo

Writing the solution

Once you finish writing the solution, you can push it to your forked repository. This will let you execute the fix and try it locally.

It is highly recommended reading/searching (normally it would be written in the file/makefile) about running the project tests. It will embarrass you and create less confidence in project maintainers about your skills if you break the tests.

It is highly recommended to add tests showing what you tried doing is working, this will create confidence in project maintainers about the code changes you make.

Merging the solution

Once you tested the solution, and know it's fully operational, you can create a Pull Request (PR) from your fork to the original repository. Once this is done, you can create an issue and attach a link to the PR. The issue will be triaged and assigned to you. Once the maintainers review your code, be open to criticism, the feedback will come.

My first open-source contribution

We had an issue with an open-source module used by our production-grade solution (back when I worked for Cisco), so I created the fix for our production servers and released it for the general public after.

This is the PR I created from my fork to the original repo:

You can see that the original branch is under my repository:

I created an issue as well, which can be seen here:

And that's it!

The next release version would normally include your changes, so get ready!

308 views0 comments

Recent Posts

See All


bottom of page