A Guide for Contributing to Any Open Source JavaScript Project Ever 💛
#opensource#javascript
Saurabh Daware 🌻

Saurabh Daware 🌻 @saurabhdaware

About: - JavaScript <3 - I make silly libraries - Building Abell, A new static-site-generator.

Location:
Bengaluru, India 🇮🇳
Joined:
May 31, 2019

A Guide for Contributing to Any Open Source JavaScript Project Ever 💛

Publish Date: Jul 4 '20
529 16

Lately, I had people asking how can they contribute to open-source projects when the codebase is large, or issues are taken, or good first issues seem difficult.

Initially, I've faced these questions as well and In this article, I will talk about how we can explore repositories, find the right issues to work on, and I will also try to answer some of the questions I just mentioned. 🐨🌻

Let's goooo 🎉

Table of Content

1. Finding the Right Repository 🕵

Contribute to something you use or find something that excites you and play around it before trying to contribute.

I will highly suggest using the tool/library/website, before contributing to it. This will give you a nice overview of what it does and how it works.

If you're uncomfortable with the process of making PR, you can first contribute to First Contributions Repository. You have to add your name to the list and send a PR! They have a nice guide to explain the process.

2. Finding the Right Issue 📚

In the issues section, you will find issues that have good first issue tag. Though it is not necessary, it is usually a sign from maintainers that 'hey these issues are relatively easy to tackle'. If you find any other issue that excites you more, go for it!

I will suggest trying to find issues related to documentation since they will be easier to get started but if you couldn't find such issues, that's ok as well you can pick whichever you like. As you get comfortable with the repository, you can go on picking more challenging issues.

And before we move forward, I know you might've heard this a lot and I am probably the 1000th person saying this but

🎉 EVERY. CONTRIBUTION. MATTERS 🎉

Even a spelling fix in documentation is a huge help to maintainers and you should totally be proud of such contributions!

Here's something I am proud of:
A screenshot of GitHub diff in my Pull Request that shows I only removed an additional bracket from the documentation

There was an extra bracket in the editor guide of DEV.to and I removed it :D

PR: https://github.com/thepracticaldev/dev.to/pull/4500

Q. Every issue is taken, how do we find one?

A lot of times in popular open-source projects, you will find that most of the good first issues are taken and someone is already working on them. In this case, you can join their chat channels. Projects use Slack, Discord, Spectrum, GitHub Discussions, or other chat channels where you can ask for help. In those chat channels, you can drop a message asking for help in finding issues. Maintainers will then help you in finding an issue for you.

Q. Did find an issue but it seems difficult...

This is very normal and even if you are experienced in contributing, you will likely find issues difficult in the first look when you're trying to contribute to a new organization.

You can always ask for help in comments of issues. Maintainers will then help you debug the problem and can point you to the right files that need changes but try exploring it yourself before asking for help.

3. Exploring Code 🤠

Before you start exploring the code, always read CONTRIBUTING.md file in the repository (If a repository does not have CONTRIBUTING.md, whoop whoop 🎉 That's your chance to send a Pull Request that adds CONTRIBUTING.md). It usually has a local setup guide and other information that you may need for contributing. You can either set it up locally and then explore, or explore on the GitHub itself and then do a local setup to make changes.

I prefer exploring locally since you get to play around and execute the code.

Awesome so now you've,
🗸 Decided the issue that you want to work on
🗸 Read the CONTRIBUTING.md

Now we exploreeeee yayyyyy!!! oh.. but wait..

Q. CODEBASES ARE HUGEE! How can we understand the whole codebase?

Fun fact, You don't have to understand the whole code 🎉

You will only have to care about the code that is related to the issue you've chosen.

3a. Finding the right files in the code.

Tip: In VSCode, you can CTRL + SHIFT + F to find something in a complete project or On GitHub, you can use the search bar to find the related code.

In websites/frontend repositories

If the project you're contributing to is a website, you can search for the words you see on the interface. E.g. If you want to contribute to the navigation bar of DEV, you can search for "Write a Post" button.

If it is not a website you can start finding the related functions by following the imports starting with an entry file.

In libraries, NPM Packages, and CLIs

In NPM packages, you would find package.json that has main attribute, the value of the main is the file that gets imported when you import/require that NPM package.

If you're contributing to a CLI, you would find bin in package.json that points to the file which is executed when you run a CLI command.

Mono-repos

Some projects like React, Gatsby, Next follow a mono repo. They have all the related projects in the same repository. In such projects, you would most probably find a folder called packages on root level and inside the packages you would find a folder with the name of the npm library (e.g packages/react, packages/next, packages/gatsby).

If you see the package.json file inside these packages, you would find the main key that points to the file which exports the functions that we usually import from these libraries.

Example

If you've used React, we usually import useEffect and other hooks like this, right?

import { useEffect } from 'react';
Enter fullscreen mode Exit fullscreen mode

Which means the package react must be exporting the useEffect function 🤔

Let's find out!

As I've mentioned earlier, the mono-repos usually have a packages folder and inside that there is a package with the name of the NPM library ('react' in this case). So let's go inside packages/react/ 🚀

Now we want to find the entry file so we will look into package.json file.

Package.json of React has {'main': 'index.js'} which means everything that we import from react package, has to be exported from index.js. Let's see if it has useEffect function!

A screenshot of index.js file that shows it actually has useEffect function in exports

Whoop whoop 🎉 Yes it does!

Now you can follow the imports to that function to find a file that handles useEffect logic.

3b. Projects that require additional knowledge

If you've been building websites and webapps and then see the source code of React, the code will look different. Some repositories require knowledge of few additional topics which you may not come across otherwise.

Some projects are built on top of Abstract Syntax Trees whereas some repositories use a different language/libraries.

It is likely that you will find this code difficult in first look but more than difficult, it is different. It is different from what we JavaScript developers usually come across.

You can spend some time playing around the codebase and if you get stuck, you can always ask questions to the maintainers.

Some Useful Links

GitHub Repositories for Initial Contributions

Resources to learn git and GitHub

Thank you for reading this 🎉 If you have any questions about git, GitHub, or contributing, you can ask them in comments or reach out to me on my Twitter DMs @saurabhcodes.

🌻🌻🌻🌻

Comments 16 total

  • Prafulla Raichurkar
    Prafulla RaichurkarJul 4, 2020

    True, I remember contributing to your DEV Widget on a small bug like converting the username to lower cases

    • Saurabh Daware 🌻
      Saurabh Daware 🌻Jul 5, 2020

      yes yes thank you so much and it was a big bug so that contribution was super helpful! thank you so much

  • Mykal
    MykalJul 5, 2020

    Great post, Saurabh!
    I've recently started contributing to OS more frequently and have found a few really friendly repos. My favourite being blitz! a fullstack react framework that aims to be rails for react

    If you're familiar with react, next.js, and full-stack concepts, and looking for a super friendly place to start contributing to OS check it out! the whole team is super welcoming and has tonnes of good-first-issue's!

  • Hina-softwareEngineer
    Hina-softwareEngineerJul 5, 2020

    Thanks, Saurabh for the valuable knowledge. I want to know about code reviews. I don't know how to do code reviews in Github?

    • Saurabh Daware 🌻
      Saurabh Daware 🌻Jul 6, 2020

      Thank you and yes that's a great question, I'll try to write the steps here:

      1. In Pull Request, you would see a File Changes tab where you can see diff of the changes made by the PR.
      2. Then in the top right corner, you would see Review Changes button, which has three options. Comment (for casual comments), Approve (to approve the PR), Request Changes (to request any changes from the author of the PR).
      3. The comment, and approve would be straightforward, you can just type a message and approve a PR or write comment.
      4. But in case of requesting changes, you may sometimes have to point out where you want the changes to be.

      Process of Requesting Changes:

      1. You would see a + sign left to every line of code in the changes Screenshot that shows a plus sign on the left of code line You can click that plus button to comment on one line or drag it to select multiple lines
      2. Then you will get a box of comment, where you can mention what change you think the author can do, A screenshot of comment box with Add Comment and Start Review buttons If you casually want to add a comment without submitting a proper review, you can click "Add Comment" but most probably you would want to "Start Review"
      3. Similarly, you can add multiple comments to code and click Start Review
      4. When you're done mentioning changes, In "Review Changes" button in the top right corner, select Request changes and put a general comment mentioning that you've requested changes below Screenshot from GitHub that shows a comment and requested changes option selected
      5. And Submit Review.

      Finally, your requested changes will be rendered as
      Rendererd output in the conversation tab of PR that shows all the mentioned changes in a list

      Thank you and let me know if you have any other questions

      • Hina-softwareEngineer
        Hina-softwareEngineerJul 6, 2020

        Got it finally, what are code reviews and how to do it, 😃 😃 . Thanks for writing a long comment. I have a question that Is code review only done by repository owner/contributor? or like someone else can do code review in someone's repository. Like If I want to do code review in someone's repo and I have not made any pull request or i am not a contributor to that repo. Then can I do code review?

        • Saurabh Daware 🌻
          Saurabh Daware 🌻Jul 7, 2020

          Yes you can do that as well. In the PR conversation it will be marked with a grey check mark and the owner's review will be marked with a green check mark.

      • Tulsi Prasad
        Tulsi PrasadJul 21, 2020

        This really is an essential part of oss contribution! I was always afraid of this part in the beginning and probably a lot more I have to know too! This could be a part of the original post as well.

      • maxdevjs
        maxdevjsJul 23, 2020

        These comments could very well become a standalone article :)

  • Vesi Staneva
    Vesi StanevaJul 8, 2020

    Thank you very much for sharing this awesome post! Contributing to open-sourced projects really is the way to go and I absolutely share your ideas. :)

    My team just completed an open-sourced Content Moderation Service built with Node.js, TensorFlowJS, and ReactJS that we have been working over the past weeks. We have now released the first part of a series of three tutorials - How to create an NSFW Image Classification REST API and we would love to hear your feedback(no ML experience needed to get it working). Any comments & suggestions are more than welcome. Thanks in advance!
    (Fork it on GitHub or click🌟star to support us and stay connected🙌)

  • Thiago Avelino
    Thiago AvelinoJul 8, 2020

    One thing many engineers forget when contributing projects (mainly open source) is that behind the project we have people.

    We don't know the people who are on the other side (project maintainers), generating the need for communication to be clear, and we don't assume that other people have the same knowledge as us (nobody knows what we have inside our head), even some concepts being obvious I made clear in communication (issue, pull request and so on). Finally, I have no attachment to code - code is a means to get to the solution of a problem.

    When we are on the project maintainer's side: consider each (every) contribution as the person's best possible contribution, the contributor has left his or her tasks to contribute to a project that is not his or her own, try to understand why the person had an affinity to the project - this will help him or her to create a community (he or she will help you maintain the project)

    good contribution friends, I'm passionate about Open Source project \o/

  • Moyomade
    MoyomadeApr 20, 2024

    Awesome Saurabh!
    I've been finding it hard to find issues to contribute to, this will definitely be of help.
    Thanks!

Add comment