Basic Git and GitHub Usage

This page walks you through the basic steps you need to carry out when making changes you want to contribute back to ShootOFF's core code. This page assumes you have a GitHub account and a basic understanding of git.

NOTE: We do not accept new default exercises anymore. If you plan to make a new exercise you want the tutorial on Creating a Training Exercise.

Useful links:

GitHub's Forking Page
GitHub's Pull Request Page

A. Create a fork of the official ShootOFF repository phrack/ShootOFF. The fork is your copy of the repository where you can safely make and test changes without consequences for development in the official repository. To create your fork, go to the official repository's page on GitHub and hit the Fork button:

B. Now that you have a copy of the repository on GitHub you need to clone it locally. The local copy of the repository is the copy you will actually work in. Your remote copy of the repository on GitHub is the copy you will store your changes in as you work whenever you want save your current state (e.g. to get some sleep) or to make your stable changes available for feedback. To clone the repository, run the following command on the command line:

git clone https://github.com/YOUR-USERNAME/ShootOFF.git

C. Make the changes you want to make to ShootOFF's source files and commit them. You can commit all changes to your local copy of the repository by running the following command:

git commit -a -m "Commit message here"

Your commit message should reference the issue number you are working on. For example, if you were writing code to address this https://github.com/phrack/ShootOFF/issues/393 issue the issue number is 393:

git commit -a -m "Added graphics for wiki page on git basics for #393"

This ensures that your commit is linked to the issue you are working on. This link helps add additional context and documentation to the commit and it makes it easy to see the actual state of the issue as far as code is concerned in the issue itself. You should reference issues in the offical ShootOFF repository, but these references will not appear in the official ShootOFF issue tracker until we incorporate your changes in step F.

You can also close an issue with a commit message by putting the word "close" in front of the issue number:

git commit -a -m "Added pull request graphic to close #393"

D. Push your commits to your GitHub copy of the repository. Committing only stores your changes in your local version of the repository. To make these changes available in your remote copy of the repository you have to push them:

git push

You can push changes on all branches with the following command:

git push --all

E. While working, periodically sync your copies of the repository with the official version to ensure that you have all of the latest changes. You will need to do this before contributing your changes otherwise you will potentially cause merge conflicts. A merge conflict will guarantee your changes get rejected. To do this, simply pull the changes from the official repository to your local copy:

git pull https://github.com/phrack/ShootOFF.git master

At this point, assuming there were new commits merged into your code, you will want to push to ensure that all of the updates you have in the local copy of the repository end up in your GitHub version.

F. Create a pull request to get your changes into the official ShootOFF repository. After pushing, your changes are in your GitHub copy of the repository, but they are still not in the official repository where they will benefit everyone. To get your changes into the official repository, you need to ask us to pull commits from your GitHub copy of the repository. You do this by creating a pull request. Navigate to the main page for your GitHub version of the repository (url: https://github.com/YOUR-USERNAME/ShootOFF) and click the "New pull request" button:

We'll get an email notification about your request and will get to it as soon as we can. We'll review your request and either accept it, in which case all of your changes will be immediately incorporated into the official code base, or we'll provide you feedback on what needs to change for us to be able to accept it. Assuming things need to change, we'll reject your request by closing the pull request at this point. Discussion of your changes can and should continue after we've rejected your request, but you'll need to submit a new request after you've made additional changes.

Guidelines for successful pull requests:

• Use the source code formatter in Eclipse with the custom ShootOFF profile. To do this import formatter.xml from the root of the ShootOFF repository into Eclispe by clicking Window -> Preferences and then navigate to Java -> Code Style -> Formatter. You can use the formatter by either highlighting code and hitting Ctrl + Shift + F or by right clicking a source code file in the Projector Explorer and clicking Source -> Format.
• Write unit tests for your changes. If you add new appropriate unit tests to go along with your changes or make reasonable changes to existing unit tests it will be much easier for us to accept your request without a second thought.
• Run all unit tests before pushing your changes. The unit tests are there to ensure you don't accidently break something in ShootOFF and to ensure the code works as it should. The continuous integration server will run all of the tests on your pull request (assuming the changes are in the master branch), and we will reject any request with failing tests. Save everyone the time of waiting for the continuous integration server to finish and just run the tests locally before even committing to ensure all tests pass first (your personal laptop is almost definitely substantially faster than the resource constrained VM created to run the test by the continuous integration server).
• Work on open issues, don't just send us a random pull request! If there is not an existing issue that covers what you want to do, open a new issue. This will give us a chance to discuss if we need to before you do anything, and it will add all the nice traceability you get when referring to an issue in a commit message. It will also let us know to expect a request on a specific topic soon so that we can prepare ahead of time.
• Do not be discouraged if we ask you to make a few fixes before we will merge your pull request. Typically, we do accept code immediately after such corrections are made. Unfortunately, it is quite common for people to expect ShootOFF's core contributors to accept and finish their buggy, 80% complete code for them. We have our own buggy, 80% complete code to work on and are not interested in directly working on yours.