Hacktoberfest: How to Submit Your First Pull Request on GitHub

###Introduction

Hacktoberfest is a month-long celebration of open source software, run by DigitalOcean and open to everyone in our global community. To participate, you’ll need to submit four quality pull requests to public GitHub repositories in the month of October. Upon completing the challenge, you’ll earn special prizes, including an exclusive Hacktoberfest t-shirt.

You can sign up anytime between October 1 and October 31, and we encourage you to connect with other developers and Hacktoberfest enthusiasts for virtual events and information sessions, starting in September.

In this tutorial we’ll introduce you to Git, the version control system that you’ll use to submit your pull request, and GitHub, the repository hosting service that we’ll be using to track your progress. By the end of this tutorial, you’ll be ready to submit your first pull request and will be well on your way to participating in Hacktoberfest!

##Version Control

Before we begin with Git and GitHub, let’s talk about version control. When developers work on a project together, oftentimes they’ll need to work on the same code base. While they’re working, each developer needs to know about what changes the other developer made, so as not to duplicate work or write code over what has already been done.

A version control system serves as a saving program for code, where it assigns a version to a project and tracks changes made over time to each file in the project. In this way, developers can work together on a project by checking in with the latest version, to see the changes made before working on their portion of the project’s code.

##Git and GitHub

Git, a version control system used to manage developer projects of all sizes, was created in 2005 by Linus Torvalds, the creator of Linux, to help developers contribute code and share code revisions in a way that was fast, efficient, and inexpensive. Git enables developers to edit, share, and publish code, facilitating collaboration and teamwork.

GitHub is a cloud-based git repository hosting service that allows developers to take code that they’ve written on their local machines and share it with the world. It provides a way to share the version-tracked projects on your local computer publicly through repositories, or central file storage locations, and depending on the project’s availability (it can be either a public or private repository), other developers can download the project to edit the code, provide insight, and more.

To get started with GitHub, you can create an account at GitHub. For more details on how to do that, please refer to the Hacktoberfest resources page.

##Cloning a Repository

We’ll now clone and edit our first GitHub repository. First, let’s navigate to the repository that we’d like to clone. For the sake of this tutorial, we’ll use the Cloud Haiku repository. Before you clone this repository, that is, take a copy of the code on GitHub onto your local machine, you’ll need to take a copy of the whole repository into your own GitHub account. This is called a fork of the repository, and it allows you to develop your code without affecting the main code base.

To fork a repository, click the Fork button at the top right in the repository. To clone, click the code button, take a copy of the link provided, then watch as GitHub takes this repository and adds it as a copy to your account. Your name should now appear as the creator of this repository, which is a ‘fork’ of the main haiku repository.

Next, navigate to your command line interface to clone the project on your local machine.You can do that with the git clone command, which will clone, or copy, the fork that I just created from the haiku repository down to my local machine. This will enable you to make changes to the codebase locally (on your own machine).

cd ~
git clone https://github.com/sammy/cloud_haiku

##Editing Code Content

You now have a copy of the Cloud Haiku repository on your local machine, so you’re ready to prepare your contribution. Using the command line interface, navigate to the folder of your cloned repository. If you followed along, you should have a cloud_haiku folder inside your home directory:

cd ~/cloud_haiku

There’s a number of text editors and Integrated Development Environments (IDEs) that you can use to edit your code. IDEs are typically segmented by programming language and include a series of helpful features to streamline the process of developing an application in that language. If you don’t have an IDE currently set up within your work machine, consider checking out Hacktoberfest’s resources page for advice on how to choose an IDE.

It’s important to take the time to read and understand how the project is organized and the contribution guidelines, and find parts of the code that you can work on. Read any associated documentation provided before making changes. Next, let’s submit a haiku!

##Adding Content to the Remote Repository

Now that we have a change made to the haiku repository, we’ll need to track and save that change. The first step in tracking your change is to add it to the version you’re working on. To do that, we’ll execute the command git add . :

git add .

Writing the command in this way allows you to add all changes made to the repository, across files. If you need to only submit changes to an individual file, use git add filename:

git add sammyhaiku.md

After running the add command, you’ll get no confirmation. To see if your changes have been included in the list of files that is ready to be committed, you can execute the command git status:

git status

This allows you to check on the status of your tracked changes — you’ll see that your file has been added, but not committed as a change. Git provides this step in the event that you need to amend a change before officially tracking it as new or edited code.

Next, let’s commit our change. Execute the command git commit, and add a message so that other developers who are collaborating on this project will know about the changes you’ve made:

git commit -m "added sammy haiku"

Writing your commit with a message allows developers to be informed of changes that are made — this message is tracked along with a commit ID and your username.

After committing, we’ll need to push changes from our local machine to the remote repository on GitHub. To do this, let’s execute the command git push:

git push

Here, we can designate an origin for the push — in this instance, we want our contributions to go to our forked version of DigitalOcean’s haiku repository.

To recap, so far we’ve identified a repository that we’d like to edit, and took a copy of the repository into our GitHub account and local machine using fork and clone. We made a change, and submitted our change with git add. We then solidified our change by running git commit, which committed the change. git push pushed our change from our local machines to the remote repository on GitHub. If we look on GitHub, we’ll see that the change we made is reflected in the files in our copy of the haiku repository.

##Creating a Pull Request

We’re now ready to let the maintainers of the project know that we have a change to the repository that we’re confident about and ready to submit. To do this, we’ll click the pull request button to the right.

After the pull request button is clicked, a new page will open with a form that explains what change we made, and shows if the changes made will in any way conflict with the existing content. We’ll add in an appropriate title that details the change, and in the description add an explanation of what changes were made and why. What you add here can vary depending on the project - take a look at the project’s collaboration guidelines to make sure your pull request is formatted correctly.

After adding in a title and description of the changes made, we’ll scan the pull request page to make sure that our committed change does not conflict with existing changes made to the code repository. If everything checks out, we’ll get a green submit pull request button at the bottom that escalates our request to make a change to the original haiku poem codebase, a contribution that will be live for anyone viewing that main branch. Be patient — it may take maintainers some time to review your request. Amendments and comments can be added on the pull request page, and new commits made to the same affected files will appear in the request’s history.

Congratulations- we’ve successfully submitted our first pull request!

#Conclusion

In this tutorial, you learned about Git and GitHub, and successfully identified and submitted a change to a public repository. For Hacktoberfest, you’ll need to submit 4 meaningful pull requests, so again, find the project that resonates with you and have fun hacking!

To see this tutorial in action, here’s a helpful video that walks you through the process of submitting your first pull request:

For more information about Hacktoberfest, visit our main page. To learn more about Git, visit How to Use Git: A Reference Guide. For additional information about GitHub, visit GitHub.