Creating a pull request: Contributing to open source projects
Articles,  Blog

Creating a pull request: Contributing to open source projects


Hello! This is Doug Tidwell, coming to you from the City of the Oaks, Raleigh, North Carolina, and if you bought a new car or truck anywhere else, you probably paid too much. In this video, we’ll talk about contributing to open source, specifically how to create a pull request. We’ll fork a git repo, we’ll make a change, and we’ll create a pull request asking the maintainers of the project to make our updates part of the code base. The example we’ll use today is the Command Line Heroes game. It’s a node and HTML5 project led by Jared Sprague and Michael Clayton and it’s available at the URL on your screen. (https://github.com/CommandLineHeroes/hero-engine) To this point, dozens of people from around the world have expressed an interest in contributing to the game, so we’ll use that project to show you how to get started. Go to the GitHub URL on your screen (https://github.com/CommandLineHeroes/hero-engine) When the page loads, you’ll need to log in to your GitHub account if you’re not already. You’ll see the Fork button in the upper right-hand corner, along with a counter that shows how many times this code has been forked. The higher the number, the more active the project and its community. Click the Fork button and within seconds you’ll have a fork that contains all of the code from the original repo. Now go to the command line or your favorite development environment and clone your forked repo. To be ecumenical we’ll use the command line. All of the commands here work on Linux, the Mac, and Windows. We’re assuming you have node and npm installed on your machine already. If not, visit nodejs.org to download and install them. Now run npm install to get all of the project’s dependencies on to your machine. We’re speeding this up on the screen because all of those dependencies require… roughly 14,000 new files and directories. Just another day in the life of a node developer. By the way, in keeping with the rich and storied tradition of laziness we’ve established in these videos, feel free to ignore any security warnings you get during the install. Or, of course, feel free to fix them and submit a pull request. At this point you need to look in the package.json file to see how to run the code. Right now the contributors to the project are focused on building the engine for the game, so we’ll run the examples they’ve put together. Type npm run examples to start the code. Now you can open a browser and go to localhost port 8080 to see this page. Take the Reference Room link to see the various examples. The one we’ll focus on here is the sprite animation. As you can see, this features a pink, minion-y figure bouncing across the room. After watching this little thing walk back and forth, you decide you’d like him or her or it to be much bigger. Soooo, off to the code we go! A big part of contributing to any open source project is learning how the code base works. Looking at the files, there is a directory named examples. That sounds promising, so look there. Now you’ll find something called reference_room. Since that’s the name of the link you took to get to the examples, go a level deeper. And there’s a directory called sprite_animation. It seems reasonable that the page you saw came from these files. Looking at index.html, that’s basically just a shell that imports some JavaScript files. So take a look at sprite_animation.js. There’s obviously a great deal of knowledge about the gaming libraries and other code behind this, but as you scroll down, you can see that this code is nicely commented. Well-commented code shortens the learning curve for any kind of project, and it’s a great way to help newcomers become part of an open source community. There’s a comment that says, “Make player a bit bigger,” followed by setting the variables scaleX and scaleY to 2. Change them to 4, save the file, and rerun the code. Now when you go to the sprite animation room, sure enough, the character is bigger. Pleased with yourself for changing the code successfully, and, at least in your opinion, making things better, it’s time to submit your pull request. First, make sure you do a git add / commit / push to put your changes into the forked repo. Now go back to your browser and the GitHub page for your fork. At the top, click the Pull requests link. From there, click the big, green New pull request button. This takes you to the original repo and assumes that you’d like to create a pull request from your forked repo. You can change forks and branches, but the default is what you want here. GitHub shows you that the only changes here are the two variables in the sprite_animation.js file. Now click the green Create pull request button. The title of your pull request is whatever commit message you used when you pushed your code into the forked repo. Beneath the title, you should add a description of exactly what you changed and why you think those changes are a good idea. If you fixed a bug, describe the problem you found and how you solved it. If you updated the documentation, describe what you changed. In our case here, you’re making an aesthetic change, so try to justify the larger size of the minion-y thing. You can use markdown in the text area, and you can also also attach files if you think they’ll help. When you’ve made a good case for your changes, click the green Create pull request button and you’re all set. Now the waiting starts. There are four things that might happen to your PR. The first is, well, nothing. Crickets. You’re a ghost. Don’t take that personally, and be as patient as you can. Lots of maintainers are volunteers who balance managing a community with a full-time job and a family. Maybe the maintainer is on vacation. Maybe it’s their kid’s birthday. Maybe they’re swamped at work and can’t give your PR the time it deserves. In an active community, you’ll probably get a response within a work day or two, but always try to think the best of the maintainers while you’re waiting. The second response, of course, is a rejection. In this example, you’re just making a change because you think the bigger minion looks better. That’s a matter of taste, and the maintainer isn’t obligated to value your artistic opinions over their own. Whatever the situation, hopefully the maintainer is gracious and thoughtful in rejecting your request. The third thing that might happen is victory. The maintainer thinks your changes are a swell idea, so they accept the PR and make your changes part of the code base. The fourth option, however, is that the maintainer sends you a request for changes. Maybe your suggested change gives the maintainer an idea. Instead of making the minion larger by default, maybe the minion’s size should change at certain points in the game. The maintainer might ask you to make the minion’s X- and Y-dimensions parameters to the function. For the sake of the community, that’s the best possible outcome. You make a simple change, that change gives the maintainer an idea to expand the functionality of the project, and you get the chance to make that change. Everybody wins. Hopefully the maintainer loves your updated PR and accepts it, but there could still be more iterations before you’re through. Remember, it’s all about the community. Before we go, let’s take a look at the pull request history for this project. For PR #15, user nwforrer added to the code so that clicking on an object can turn the ceiling light on and off. As you can see, Jared happily accepted the request. Request #17 was a fix to the documentation. It’s important to remember that there are lots of ways to contribute to an open source project beyond code. Every project needs documentation, and the Command Line Heroes game needs artwork as well. Jared’s gracious response here is a great model for maintainers everywhere. So those are the basics of creating a pull request, your first step towards becoming an active member of an open source community. It’s not hard to do; the trick is to find a project you care about and find a way to make it better. You might be creating or fixing code, documentation, artwork, or something else, but now, you’re a contributor. We encourage you to keep an eye on the hero-engine repo. Watch the game as it evolves, and don’t hesitate to join the community and contribute. Or join any community you care about, just get started. There’s no limit to what you and a great community can accomplish. For the Red Hat Developer program, this is Doug Tidwell saying, may all your bugs be shallow. Cheers.

One Comment

  • Sébastien Dubois

    14.000 new files… Just another day in the life of a node developer. This is my quote of the day ;-))))

    Keep up the great work, the OSS community always needs more brain power! :p

Leave a Reply

Your email address will not be published. Required fields are marked *