---

WARNING: the following is no longer up to date. Pull requests should be created as proper feature branches and always based on/targeted against the test branch of OpenPnP.

See this tutorial about feature branches (just an example, there are many other tutorials and guidelines).

HELP WANTED! The following should be rewritten to reflect a proper feature branch workflow. HELP WANTED!

---

A step by step tutorial to help new contributors submit their first pull request. By the end of this tutorial you will have a basic understanding of Git, Github and Pull Requests.

OpenPnP, and many other Open Source projects maintain their source code and project files in a Git repository. Git is a version control system which allows people to keep track of changes to files over time. The benefit of using a version control system is that you can go back in time and see every change that has ever been made to a project. This is very helpful when trying to find bugs.

A Pull Request is the Git way of asking the maintainer of a project to accept some changes you'd like to make. In most projects there is a small team of maintainers who do development and accept changes from other people. They make sure the changes fit into the architecture of the program and help to catch problems before they are distributed to users.

Github is the most popular Git hosting platform in the world. At it's heart it is a way to manage one or more Git repositories but it also adds very useful things like issue tracking, wiki pages, collaboration and web based code viewing. Git and Github are separate things. Git is the version control system and Github is a very nice front end for using Git.

Before we get started, you'll need a Github account. It's free and only takes a second to sign up. Once you have one you can contribute to OpenPnP, create your own repositories, file issues and bug reports, create wiki pages and all kinds of stuff.

You can create a Github account at https://github.com/join. You should do that before continuing.

In this tutorial we are going to make a copy of the OpenPnP repository, make a small change to a file, commit the change and submit a pull request asking the maintainers of OpenPnP to accept the change. It sounds complex, but it's really easy, and Github makes it even easier!

1. To get started, make sure you have created your Github account and signed in.
2. You'll need to install the Git command line tools. You don't always have to use the command line, and in fact I recommend you don't, but this tutorial uses command lines because they are compatible with every operating system. You can learn how to install Git at https://git-scm.com/book/en/v1/Getting-Started-Installing-Git.
3. Open up a new tab in your browser to https://github.com/openpnp/openpnp. You'll want to be able to do work in that tab while you keep this one open so you don't lose your place.

The first thing we'll do is fork the OpenPnP repository. Forking just means making a copy of the entire repository. Github will copy the OpenPnP repository from the OpenPnP account to your account. This gives you your own copy you can do whatever you want with. Don't worry, Github doesn't care how much space you use. You can fork as many repositories as you like.

Tip: We're going to start saying "repo" instead of repository because I am sick of typing repository, and repo is what everyone says anyway.

To fork the repo, go to the OpenPnP repo in your other browser tab and click the Fork button in the upper right hand corner. Github might ask you where you want to put it and you can just use your account.

Once you click Fork, Github will work it's magic...

And when it's done it will redirect you to your own copy of the OpenPnP repo!

Notice that before we forked the repo we were looking at the openpnp/openpnp repo and now we're looking at vonnieda/openpnp. The first one is the main OpenPnP repo and it's owned by the openpnp organization. The new one is owned by you (or in the screenshot, me) so it shows up under vonnieda. That's my username. Yours will be your username.

Now that you have your own copy of the OpenPnP repo you can copy it to your computer so you can start making changes. In Git land this is called Cloning. Cloning is similar to Forking, and behind the scenes that's actually what Github does when you Fork a repo but to keep things straight we'll use the terminology that Github uses.

To clone the repo, look for the Clone or Download button on the repo page and click it. You'll see an icon that will let you copy the URL of your repo, and you should click that.

Tip: Ignore the blue button that says Download Zip. You want the little clipboard button next to the URL.

Important Tip: Make sure you are looking at YOUR fork of the repo and not the OpenPnP one. Remember, the name up top should be your_username/openpnp, not openpnp/openpnp. If you've ended up back on the OpenPnP one, just click your avatar in the upper right corner and then click Your Profile. You'll find your fork of the repo listed there.

Okay, now you have the repo URL in your clipboard so it's time to clone! Open up a command prompt on your computer and type git clone and then paste in the URL. Hit enter to get the ball rolling.

You should see something like this:

When it finishes, you'll have a clone of your OpenPnP repo on your computer. It will be in a subdirectory called openpnp.

Tip: Don't forget where you placed your repo. I like to keep all my repos in a directory called Projects. So on my computer my repo is under Projects/openpnp.

Before we get down to making changes, let's take a little break and read the OpenPnP Developer's Guide. You don't have to read the whole thing right now, but you should definitely read the Building OpenPnP Section.

If you are a Java programmer you probably have your own preferred set of tools. The Developers Guide shows you how to use Eclipse and Maven to work with OpenPnP, but you can use whatever suits you. It won't matter for this tutorial.

For this tutorial, I'm going to make my changes in Sublime Text but everything you need to know about Git will still be done at the command line.

With that out of the way, it's time to...

This is the fun part. This is the reason we're here! It's time to make OpenPnP better.

We're going to make a small change in the OpenPnP code and ask the maintainers to accept it. Let's say that you want a more friendly welcome message when OpenPnP starts. This is definitely something we can improve.

Open up the file src/main/java/org/openpnp/Main.java in your repo. You can use whatever editor you prefer. Remember, it's in the openpnp directory that Git cloned for us.

With the file open, scroll down to the line of code that outputs the welcome message.

And let's change it to make it a little more friendly:

Now save the file and head back to the command line. You've made your change and now it's time to tell Git about it.

Tip: If you haven't already switched your directory to the openpnp directory, do that now:

First we will check to see what in the repo has changed:

We see that our src/main/java/org/openpnp/Main.java is modified, as we'd expect. git status gives us some tips on what to do next.

We want to add the file we changed to the commit.

Note: A commit is a set of changes with a description message, a date, and a time. The history of a project is made up of it's commits, going back to the very first file that was added.

Git doesn't bother to tell us that it did anything, but that's okay. We can check for ourselves:

We run git status again and now we see that our file is listed under "Changes to be committed:" and the filename has changed from red to green.

Finally, we commit the change!

After you run git commit you will be presented with an editor with an open file and some comments. It should look something like this:

It's okay if it doesn't look exactly the same. It may be in a different editor, depending on how your operating system is configured.

This editor window is where you type your comments about what your change does. This is called the commit message. The commit message will be recorded into the history of the project so that other developers can learn what a given change did or why. It's important to write short but descriptive commit messages. Try to describe what the change does and why.

Go ahead and type your message, then save the file.

Back at the command line now, we should see that our commit was created!

Now that we've committed our change we need to tell Github about it. When you commit a change it goes into the clone of your repo on your computer. Your repo on Github doesn't know about it yet, so you have to push the change.

Now that the push is complete, the repo on your computer and the repo on Github should be the same. Let's check, to be sure. Go back to your repo on Github and refresh the page.

Notice that the blue section that shows the last commit has changed to show the commit we just made. This means our change was pushed from our local repo to our Github repo. Github even shows a little Pull Request button above it, which means we must be getting close to making a...

Finally. It's time to submit the pull request. We're going to let the OpenPnP maintainers know that we've made a change we'd like to release, what the changes are and why we made them. Let's jump in...

Go ahead and click that Pull Request button.

Tip: You can also start a Pull Request by going to the Pull Requests tab and clicking the button there.

Github will take you to the Pull Request creation page. There's a lot of info here so we're going to go through it section by section.

First, we'll see the Comparing Changes section. This shows our repo and the repo we're submitting the Pull Request to. It also mentions the branches. Branches are a big topic, so for now let's just make sure both are on the develop branch.

Next we see the button to actually create the Pull Request and a summary of what will be included. We see that there is one commit and the message we added to the commit is shown.

Finally, at the bottom we'll see the exact changes that we made. On the left is how the file looked before we made our change and on the right is how it looked after.

Take a minute to review your changes line by line. Did you miss anything? Did you include code you didn't mean to? Does anything look different than you expected? If so, go back to your file and make a new commit.

If everything looks good go a head and click the Create Pull Request button. The screen will change to a full summary of the Pull Request and you'll have a place you can type comments in to the people who will receive the Pull Request.

The comments field will have your commit message pre-filled in for you. If you've done a good job with your commit message this is usually good enough but you can also use this area to fill anything else you want the maintainers to know about your change.

Once you are happy with your Pull Request, click the Create Pull Request button and it's done! You've submitted your first pull request!

You will now be on the Pull Request page, but something important has changed. Notice the repo at the top is now openpnp/openpnp. You are now looking at the Pull Request that you submitted in the main OpenPnP repo. The maintainers have been notified that a new Pull Request was issued and they will begin the review process.

During the review, the maintainers will be looking for things like errors in the code, code quality, code style, and usefulness of the change. If they find any problems or have any questions they will make comments on the Pull Request for you to review. Github will notify you when you have new comments.

If the maintainers ask you to make changes before accepting the Pull Request, the process is exactly the same as what we've done so far except you don't have to submit a new pull request after pushing your changes. It will update automatically.

Once the maintainers are happy with the Pull Request they will click the Merge button that only they can see and the change will be merged! Github will kick off the process to build new installers and within about 10 minutes the change you made will be available for download to everyone in the world. You will have made your mark on OpenPnP's history!

Here's what we accomplished:

1. We forked the OpenPnP repo.
2. Cloned our fork of the repo to our computer.
3. Made a change to the OpenPnP code.
4. Committed the change to Git.
5. Pushed the change from our clone back to our repo on Github.
6. Created a pull request to ask the OpenPnP maintainers to accept the change.

Pro Git, written by Scott Chacon and Ben Straub is the best way to learn more about Git. It covers everything we've learned here and expands on each thing so that you can really understand what is happening.

Github Bootcamp is a great way to learn more about Github.