Relicans Summer Camp Week 2: Open Source Week

🏕 Challenge: Submit an open source PR to a repo that you do not own and have it reviewed or commented on by the maintainer.

Why open source?

Open source is a fantastic way to connect with other developers, work on interesting projects, build your portfolio or your library of examples, and learn new skills! In our work lives, we're often told what to build and which tech stack to use. With open source contributions, you can explore an exciting new tech stack and build what you want to see in the world!

How do I find an issue?

Issues are tickets in GitHub that describe a bug, or feature. Open ones haven't been fixed. They're used to track work.

You can find issues by searching GitHub for issues labeled "Good First Issue" or check out sites like Good First Issue and Code Triage. If you are looking at a project on GitHub, you can check to see if it has any good first issues by going to the /contribute URL for the project. For example, if you were looking at the New Relic Ruby Agent repository (https://github.com/newrelic/newrelic-ruby-agent), you could then go to its contribute page here: https://github.com/newrelic/newrelic-ruby-agent/contribute and it will tell you if there are any good first issues waiting to be tackled.

You want to look for issues that are well-scoped, small, and include reproduction steps. Anything with screenshots is going to be a lot easier to solve. You'll be in an unfamiliar codebase, so there's no reason to make your first PR an ambitious one! Extensions to existing features and bugs are great choices and a huge help!

Did you know that theRelicans.com and dev.to are run on an open source platform called Forem? If you can't find a project you like, you could always start there!

How do I claim an issue to work on?

Step 1. Read their contributing guide.

Most open source repositories store their contributing guide in CONTRIBUTING.md or README.md. This is where you'll find information about coding standards, how to set up the codebase, and their issue/review process. Sometimes this guide will link to documentation on the tool, like in Forem's case, or they could require you to sign a waiver.

Step 2. Comment on the issue.

Let the maintainer and other contributors know that you're working on the issue and how you plan to solve it. If you have any questions about the issue or how they'd like it solved, this is a great time to ask.

A maintainer is responsible for merging items into the codebase and releasing new versions. A contributor creates some value for the codebase, through code, documentation, or issues.

How do I set up the codebase locally?

Step 1. Fork the Repository.

A forked repository is a personal copy of a codebase. It only updates when you update it, and you can make as many changes as you want without impacting the upstream repository.

In the upper right of the repo page on GitHub, there is a Fork button.

Click that, and it will walk you through forking your own copy of the repository.

Step 2. Clone the repository locally.

Use git clone <the git url> on your machine to clone the repository locally. This url should be for your forked version of the repository.

Step 3. Set up any dependencies.

Most projects have documentation, often right in their README.md, that provides instructions on how to set up that particular project. It is often in the Development or Contributing section at the bottom of the README.md, or in the separate CONTRIBUTING.md file. It's a good idea to check if they have a docker or vagrant setup. If they do, you can quickly setup the repo without installing the dependencies on your computer, and you can discard the dev environment when you're done working with it.

How do I solve the problem?

Open source is a little different from other work projects, because you're being introduced to the codebase for the first time, and the issues are created by volunteers. The issues sometimes aren't verified, and far less detailed than what a good PM writes.

Step 1. Start the app and run the tests.

The contributing guide from earlier should've told you how to run the application, and run the tests. This is your first hurdle! Once you can start the app and run the tests, you can say your dev environment is successfully set up. Some frameworks, like Rails, don't have an app to start up. That's okay! Just make sure you can run all the test cases, and can confidently verify your changes.

Step 2. Reproduce the issue

Don't make a single change until you've reproduced the issue or original functionality described in the issue! Open source issues are often fixed in other PRs, fall out of date, or are insufficiently described. If you're unable to reproduce the issue, it's time to leave a comment on the issue, and pick up a new one.

Step 3. Make your changes.

This is the part you're good at! Write some tests, make some changes, and follow any style guidelines. And yes, definitely write the tests. Most projects won't accept a PR that doesn't have appropriate tests. They will remind you if you forget to include them, but it's better if you make test writing a regular part of how you work on and deliver PRs. Good tests are always appreciated!

Create the PR

A PR is shorthand for a Pull Request. Maintainers can "pull" code contained in a Pull Request into their repository.

Step 1. Push your changes to your Forked Repository.

Create a new branch (if you haven't already) using git branch -b <name of branch> then push that to your forked repository using git push.

If you git push and see the following error. You are probably trying to push to the parent instead of your forked repo.

Step 2. Create a PR.

After pushing your code to your fork on GitHub, if you look at the branch page in GitHub, you will see a Contribute link. This will walk you through creating a pull request. There'll also be a link in the git cli the first time you push to that branch.

Your pull request should describe the issue you are solving, and the changes that you made. Screenshots of any changes are greatly appreciated. You should also link the issue in your PR, (closes #1234). This will automatically close the issue when your PR merges.

Step 3. Point your PR to their main branch on their repo.

This is a matter of selecting the right branches from the dropdown boxes in the form that you are presented with. It should look similar to this:

Most repos use this method, but if the contributing guide says otherwise, follow the contributing guide.

How do I get my PR merged?

Maintainers of large repos are busy folks, and sometimes a PR can go ignored for days, or weeks. Sometimes you get a review in hours. Every repo varies, and it's a good idea to practice patience, and respond quickly to change requests. The contributing guide should tell you what's okay, and if they include a code of conduct, follow it at all times. You're asking someone to include your work in their group project. If it's your first time in a repo, they will probably want changes. But once it merges, be proud! You've helped contribute to making open source a better place, and hopefully learned something during the process!

Next Steps

Wow! Hopefully, you learned a lot about contributing to open source from this blog post. If you have any questions, feel free to ask them in the comments, or we'll be hosting a live workshop 7/13 at 17:00 UTC! When you make your first open source contribution, link the PR in the comments here and post under #RelicansSummerCamp to get your camp badge! We're really excited to see what you do!