How to Make Your First Open Source Contribution

Ceora Ford: [0:00] Hi, my name is Ceora Ford and I'm super excited to be here today to talk to you about open source and to give you a quick demo of how you can make your first open source contribution. Please remember that this is a very beginner-friendly guide, so if you are someone who's completely new to open source, this is the presentation just for you.

[0:18] Before we get started, I want to give you a little bit of an introduction to me and tell you a little bit about myself. I am a developer based in Philadelphia.

[0:27] I'm currently working as a developer advocate at Apollo GraphQL and I am someone who has struggled a lot with open source and Git in the past, so this is the presentation I wish I had when I was just getting started with open source and making my first contribution.

[0:45] But that's enough about me. I want to talk a little bit more about you. I'm going to read these statements that are here on this screen and I want you to think about whether or not you identify with these, whether or not these line up with your experience. Is this you?

[0:57] You've learned the basics of Git. You've created a GitHub account and you've built projects and used Git to upload your projects to GitHub. Now, all of this sounds great and it really is. These are all great things. These are huge accomplishments. But when it comes to contributing to open source projects, is this you?

[1:19] Do you become this Kermit the frog meme on the slide, timid and scared? If that's the case, do not worry. You are not alone. The struggle is definitely real. Like I mentioned earlier, I'm someone who has struggled a lot with open source projects in the past and I'm sure there are tons of other people who have as well.

[1:37] But that's what I'm here for today and that's what this talk is all about. I'm going to try to make the struggle a little bit easier and clear up some of the confusion for you.

[1:46] Let's start out by discussing why you should even be interested in contributing to open source. Are there any benefits for you? Why is this worth the time investment and the effort you're going to put into it?

[1:57] I'm going to outline three benefits to contributing to open source. There are plenty more, but I'm just going to stick to three for now. The first one is that you get better at Git. You get to improve your Git skills.

[2:09] You get to repeatedly use the Git commands that you already know and sometimes you even get to use ones that you probably may not have used in the past before. So you get to add to your Git knowledge as well.

[2:21] A second benefit is that you get to connect to other developers in the community. We'll discuss this more in detail later, but there's a lot of communication that goes into working with open source projects.

[2:32] You have to interact a lot with other developers and other people involved in the project and maintainers as well. This in turn helps you to build relationships with people who are already in the industry, people who are in the community. This is a really great benefit.

[2:48] The last thing that I have listed here is that you can gain practical experience. For this one, I don't want you to only take it from me. I also want you to hear what some other people had to say on Twitter.

[3:00] I recently asked, "How do you get engineering experience without being an engineer?" This is an important question to think about, especially if you were someone who comes from a non-traditional background.

[3:12] Maybe you are self-taught or you come from a different industry or you're switching from a different position at a tech company already. You want to do something that's more engineering focused.

[3:24] A lot of times, the way we think about getting engineering experience is by building projects, but many people responded to this question. A lot of them come from these non-traditional backgrounds. Many of them said that one of the best ways to gain practical engineering experience is to contribute to open source projects.

[3:41] I'm going to read you a direct quote from a response I got on this tweet. This is what this person said. They said, "I found contributing to open source to be the best because you have to get comfortable with an existing code base, understand existing issues, and then participate in code review with maintainers."

[3:58] These are all things that you have to do as a professional developer. You have to work with an existing code base, you have to understanding existing issues, and you have to do code reviews. These are things that you get to practice at when you work with open source projects. It's definitely a huge benefit.

[4:14] At this point, we've acknowledged that open source can be stressful, it can be confusing, it's hard to get started. But we definitely know that it's valuable. It's worth the time and worth the effort. You get to get more involved in the community and you can get to gain some practical development experience.

[4:30] Let's start diving into clearing away some of the confusion that goes along with open source contributions. Before we get started on making your actual contribution, let's first discuss how you can find a project you feel comfortable working with.

[4:44] This is something that I definitely found difficult. There are so many difficult open source projects out there. GitHub hosts so many different projects.

[4:53] I'm going to outline three ways that you can find a project that's just right for you. The first thing you can do is you can work with a project you already know and love.

[5:02] Think about some of the projects you know of or some products that you use and check and see if they are open source. If they are, you might be able to make a contribution.

[5:11] The second thing you can do, the second way you can find projects to work on is by looking through websites like goodfirstissues.dev, First Timers Only, and also checking out the Awesome For Beginners repository on GitHub.

[5:23] These resources specifically pinpoint projects that are welcoming to beginners and first time contributors, so I definitely recommend you look into these resources.

[5:32] The third thing you can do is you can ask developers you know or people in the community for suggestions. You can ask on Twitter. You can go to any developer-focused communities you're a part of on Slack or Discord.

[5:44] You can even ask people you work with for any suggestions. You might be surprised by the number of people of developers who have active open source projects that need contributors right now.

[5:56] I suggest that you gather more than one project so that you can have some backups just in case the first or second or third one doesn't work out for you and then set them aside.

[6:04] I also suggest that you go through each of these methods for finding a project so that you can create a nice little collection of open source projects.

[6:13] Once you've got your project chosen, there's still some more things that we have to go through before you're actually ready to get your hands dirty with making your contribution. One of those things is communication and how to effectively and respectfully communicate with open source maintainers and others involved with the project.

[6:29] Like I mentioned earlier, there's a lot of communication that goes into working with open source projects. I want to cover five communication guidelines that will help make this as smooth as possible.

[6:40] The first one goes for any form of online communication, and that's be polite, patient, and kind when talking to anyone involved with the project. The reason why you want to follow through with this is because it's really important to remember that maintainers have lives outside of GitHub.

[6:54] Sometimes they may take a long time to respond to questions or merge pull requests, but when this happens, be patient with them. Like I said, they have lives outside of GitHub.

[7:04] Also if they don't agree with a feature you're suggesting or a code that you're trying to implement, stay calm and respectful. Don't take it personally.

[7:12] Let's move on to communication guideline number two, which is to read through the whole readme and/or contributing markdown documents and follow the structure and guidelines the maintainers have specified within.

[7:25] Most active open source projects will contain one or both of these, usually both. I'd highly, highly recommend -- this is actually a must -- that you read through these.

[7:36] Because maintainers will likely tell you how they want you to communicate with them and they also have a bunch of other important information, sometimes how you can structure your pull requests, how you can structure even the code that you're writing, what version of the software you need to be using, all that kind of good stuff. Definitely look through these before you work on your contribution.

[7:59] Communication guideline number three is when you open an issue, thoroughly describe the bug or problem you run into and include all relevant information. Do this so that maintainers can possibly recreate the bug on their end and understand thoroughly the problem that you've run into.

[8:16] Then communication guideline number four pretty much builds off number three, which is after describing the bug, provide a possible solution if you have one in mind.

[8:24] This streamlines communication, cuts down on back and forth conversation. It will also help maintainers quickly determine whether or not your possible solution fits the direction of the project.

[8:35] On top of pointing out the bug and describing the bug, also describe your possible solution again to make sure that communication goes as smoothly as possible.

[8:47] Communication guideline number five is to include comments in your code. This is something that you should always do. This should be a given, but I know for myself especially with personal projects I tend to forget to do this. You might do the same.

[8:59] But it's especially important when you're working with others to include comments because other people aren't familiar with your coding style or how you think, especially if this is your first time contributing to a project.

[9:10] Including explanatory comments in your code will make your logic very clear. This will also in turn make it easier for others to quickly understand how your code works. Again, it streamlines communication.

[9:22] Here's a quick reminder before we move on from covering communication guidelines. Whatever is in the readme or contributing file is the most important. It trumps anything we've talked about thus far. If you read those and it contradicts the guidelines I've set out, go with whatever is in these files.

[9:40] Before we move on, let's do a quick recap. You've got your project chosen. You already know what project you want to work with. Now we know how to talk to maintainers and other contributors and how to collaborate effectively with them.

[9:57] Let's go over how you'll actually choose the change that you want to make to the project and different ways you can contribute to an open source project. Right now is a good time to possibly open up GitHub and pull up a project so that you can follow along. It doesn't have to be the one that you actually want to work on.

[10:16] It can be just a random project that you found before, that you find as soon as you open up GitHub. I'm going to be working with the self-defined open source project that is maintained by Tatiana Mac. I recommend that you can also open that up as well. You can search it. It's called self-defined app. I believe you can open that up quickly so that you can follow along.

[10:36] The reason why I'm telling you to do this is because, moving forward, I'm going to reference the GitHub UI a lot. I think it would be easier for you to understand if you follow along with me. I'll give you a couple seconds to do that.

[10:49] Let's move ahead and go back to discussing how you can figure out what you want to add to the project.

[10:57] The first thing you can do, the first option, is to work on a pre-existing issues. These are issues that maintainers and others have seen in the project that need work. Maybe it's a bug or something that needs to be added. You can find these by going to the issues tab on the repository dashboard.

[11:20] I'll show you how to do that, where that is exactly right now on the GitHub UI. Like I said, I'm in the self-defined project repository. I'm going to go under issues. As you can see there's a long list of issues that Tatiana and others that work with the project have pointed out that need help.

[11:41] One really awesome thing that a lot of maintainers do is they use the good-first-issues tag or the first-timer-only tag. These are issues that are made specifically for beginners or for people who are new to open source. These are issues that you should definitely check out and I'll show you how to again.

[12:01] The third and fourth issues shown here have the good-first-issue label. Like I said, these are issues that are specifically designated for beginners or people who are first timers with open source.

[12:20] You can also specifically only look at issues with this tag or this label, I should say by going to the labels tab here and clicking on good first issue. You can see the plethora of good first issues that are in this project for people just like you.

[12:38] Before we move on to option number two, let's discuss this one tip. Once you find the issue you want to work on, leave a comment that explains your possible solution, or this is even the time for you to ask questions, clarifying questions about the issue.

[12:52] Again, I'll show you what that looks like here. I'm going to click on this first issue here. As you can see, there's some information here left by the maintainer and then I can leave a comment here. I can explain how I want to solve this problem, or I can explain or I can ask questions that could help me better solve the issue.

[13:10] Now, let's move on to option number two, which is to open a new issue. Just like how maintainers make issues you can also create your own issues as well. You can do this by clicking on the new issue button. It's shown here on the screen shot here.

[13:26] Again, I'm going to show you what that looks like in the actual GitHub UI. You can see it right here, the new issue button and it's even under, again, the issues tab. That's where you have to navigate to the issues tab to find the new issue button. Let's go over another tip.

[13:48] If you decide to do this, to provide relevant information that will either help maintainers to, A, understand the bug you've noticed or, B, understand what feature you want to add or enhance and why. The reason why you want to do this is again to get the communication lines open between you and the maintainers or others involved with the project.

[14:06] It's a place for you to describe thoroughly, going back to the communication guidelines we discussed earlier to thoroughly discuss with maintainers whatever solution you're bringing to the table or the bug you've noticed, all that kind of good stuff.

[14:21] Again, when you click on the new issues button, all of that is right there. You can include a relevant title that is relevant to the issue you want to solve or the issue you noticed. Again here, you can just solely explain the bug that you run into and, if you have a solution in mind, this is the place where you would also describe the solution that you want to implement.

[14:44] Let's move on to the third way that you can make a contribution to the project which is making a pull request. We'll go into how you can do this later on, but I recommend that you only do this, if you are already very familiar with the project and the maintainers.

[15:00] I say this, because when you do this method, you can skip creating an issue and you just go straight to submitting the pull request. It cuts out all the communication that goes into creating the issues, submitting issue, and discussing back and forth with the maintainers. You can get right to work, but I have the red warning lights here for a reason.

[15:24] The project maintainer may decide to decline your pull request. The work you've done may not be used in the end and this could be sad because it means that you may have wasted some time. Of all the options that we've discussed so far, I recommend starting with a pre-existing issue that maintainers have already designated and going with one of the good first issues.

[15:49] With all these steps down, you've got your project chosen. You know what issue you're going to work on. You know what you want to add. It's time to finally get to work. You can finally get ready to make your contribution. This is where the good part is.

[16:03] This is where you get to get your hands dirty in some code or design changes or whatever you decide that you want to work on. The first step is to fork the project you've chosen. This will create a copy of the project onto your personal GitHub account.

[16:17] I'll show you what that looks like in the GitHub UI right now. I'm going to go back to the original dashboard, just to show you what that looks like, if you're completely starting from scratch. I would click this button right here that says fork. I'm going to copy it over to my personal GitHub account. As you can see, that's what's happening now.

[16:39] If you look, my username is in front of the app name. That shows that it's copied onto my account. Once you've done that, you're ready to move on to step two, which is cloning the project locally. You're going to clone the fork that you just created. I'm going to show you what that looks like again.

[16:58] First, you're going to click on this code button here and you're going to copy the URL that is provided to you. This is going to allow you to download the project onto your personal machine so that you can open it up in your code editor and get to making your changes and all that kind of good stuff.

[17:15] To download this project onto your machine, you're going to have to open up your terminal. We're still in step two. Just going to have to open up your terminal and clone the project using Git commands and then CD into the project.

[17:28] I'm going to go into my terminal to show you what this looks like. I'm in my desktop right now. I'm just going to remove my cap locks.

[17:37] I'm going to get clone. I'm going to copy. I'm going to paste the URL that I just copied earlier here. As you can see, all the Git magic is working and I'm copying the project to my computer. Then I can CD or change directories. This project is called "Web App," so I'm going to change there. "Web App."

[18:06] As you can see, I change into the directory and, once I press LS or type LS, you'll see that all the files and folders that are on the remote repository on GitHub are also now on my computer.

[18:19] We can now move onto step number three, which is to create a branch locally. You want to specifically create a branch that is going to be the home for all the changes that you make. You don't want to push all your changes to main, so you want to create your own branch.

[18:35] I usually like to make sure that the name of my branch is relevant to the change that I'm making, the issue that I'm working on, or the feature that I'm working on.

[18:46] You're going to use the Git checkout dash B command. Like I said, I'm going to just type relevant title here. Relevant name, I should say, here.

[18:58] I'm not going to actually enter this because I'm not actually contributing to this project, but again I think it's best practice to make sure that this is a name relevant to whatever you're working on. It's going to make things easier for you and maintainers in the long run.

[19:14] Let's go ahead and return back to our slides and move on to step number four, which is making your changes. This is where you get to get your hands dirty and code. I want to leave a quick disclaimer here because I want to remind you that the changes that you can make don't only have to be code changes.

[19:34] They can be changes to documentation or updates in documentation or editing copy or correcting grammar that you've seen in the copy on a website. Things like that are all valid changes that you can make to a project.

[19:48] Once you've made your changes, now it's time to return back to some of the Git stuff that you have to do. Now, you have to add your changes, commit your changes, and push your changes. Like I said earlier, you should have some of the basic Git knowledge so I'm not going to go into detail about how to carry out all these commands or what they actually do. You should know that already.

[20:10] But you're going to Git add your changes, you're going to commit them with an explanatory commit message, and you're going to push them onto your remote forked repository on GitHub. Once you've done that, there is one more step, which is creating your pull request.

[20:30] Once you go onto the remote repository that you've forked, you're going to see this banner at the top of the dashboard that's going to have this green button and it's going to be highlighted in kind of a faint yellow. It's going to be a green button that says compare and pull request.

[20:48] You're going to push that. It's basically saying, "We are aware that you have made some changes and pushed them. Do you want to compare them to the original repository and make a pull request with the original repository?" Yes, we do.

[21:01] Click this button and you will get a text editor that comes up very similar to when you make an issue and all that kind of stuff. Again, this is a place where you can leave any relevant information. Sometimes this is prefilled by the maintainer like a fill in the blank kind of thing where you point out whatever information they want to know specifically.

[21:26] But you can tell them what change you made, describe the change you made, why you made it, any issues you ran into, how you solved those issues, things like that.

[21:36] After this, you have to wait. Now, you have to wait for the maintainers to approve your request, make sure your request and code passed all the tests that they have in place and all that good stuff.

[21:51] Once they look at your pull request, maintainers may decide to accept your pull request, which is great because that means that you're officially an open source contributor, which is the whole point of this. That would be awesome.

[22:03] Sometimes maintainers might have some suggestions that they'll make, slight changes they want you to make in your code or whatever the case may be. If that's the case, just go along with the changes that they're suggesting.

[22:16] They might also decide to reject your pull request. If this happens, like we said earlier, don't be discouraged. Don't be upset. Maintainers will probably have a good reason for doing this. Even if they originally approved it and said that it went along with the vision of the project, they may change their mind in the meantime.

[22:33] They'll likely let you know if this is the case. You can also from there decide to work on another issue in the same project or you can pick from the collection of projects that you chose earlier to work on a new project.

[22:49] Hopefully, by the time you've reached this slide, maybe you're rewatching this, you're officially an open source contributor, which is great. This is the time to do your victory dance or get yourself a little treat, some ice cream, something like that.

[23:02] This is the whole point of the presentation and I hope that you can reach this point. If you do, please let me know that you've successfully made your first open source contribution with the help of the presentation.

[23:14] You can DM me on Twitter. I'll show you my at I think in one of the next slides. Let's move on and wrap things up with the six step framework. One of the hard things for me was remembering specifically the steps I had to take to make my contribution.

[23:32] I've created these acronyms that are going to help you to remember the steps. This is what I wish I had when I was getting started.

[23:38] The first three things you do is you fork the project, you clone your fork, and then you create a branch. The way that I remember this moving forward is free cheeseburgers. The F stands for fork. The C in cheese stands for clone. The B in burger stands for branch. So remember free cheeseburgers for those first three steps.

[23:59] Then the last three steps are you make your changes, you commit and push your changes, and then you create a pull request. The phrase that I use to remember these things is cooking pepperoni pizza right now.

[24:16] The C in cooking goes for commit, the P in pepperoni goes for push, the P in pizza goes for a pull, and the R in right goes for request. I left the now there because it just makes the phrase make more sense. Just ignore the end there.

[24:32] We've reached the end of the presentation. I want to thank you so much for watching. Maybe at this point, you've realized you need more information. Maybe the acronyms don't really work for you. If that's the case, that's totally fine.

[24:43] I actually have all of this information written out with some extra resources. It's in an article on dev.to, so you can go to dev.to and you can search up this title, "How To Make Your First Open Source Contribution."

[24:54] It's going to be under my account, ceeoreo, so that's C-E-E-O-R-E-O. You can either search up the title or search up my username and it will be under my account. I also have an open source resource thread that I'm going to post as soon as this live replay of this talk is done. Go check out my Twitter at ceeoreo_, that's C-E-E-O-R-E-O-underscore.

[25:17] Like I said, if you learn something new or you were able to make your first contribution through this presentation, please let me know. I love getting messages like this. You can either at me in a tweet or you can DM me. My DMs are open. Thanks again for watching. I really hope you enjoyed this.