Skip to content

How To: Submit A Pull Request

Jump to bottom Edit New page
SilentMike edited this page Oct 21, 2013 · 1 revision
<style type="text/css">

html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video { margin: 0; padding: 0; border: 0; }

/* BODY =============================================================================*/

body { font-family: Helvetica, arial, freesans, clean, sans-serif; font-size: 14px; line-height: 1.6; color: #333; background-color: #fff; padding: 20px; max-width: 960px; margin: 0 auto; }

body>*:first-child { margin-top: 0 !important; }

body>*:last-child { margin-bottom: 0 !important; }

/* BLOCKS =============================================================================*/

p, blockquote, ul, ol, dl, table, pre { margin: 15px 0; }

/* HEADERS =============================================================================*/

h1, h2, h3, h4, h5, h6 { margin: 20px 0 10px; padding: 0; font-weight: bold; -webkit-font-smoothing: antialiased; }

h1 tt, h1 code, h2 tt, h2 code, h3 tt, h3 code, h4 tt, h4 code, h5 tt, h5 code, h6 tt, h6 code { font-size: inherit; }

h1 { font-size: 28px; color: #000; }

h2 { font-size: 24px; border-bottom: 1px solid #ccc; color: #000; }

h3 { font-size: 18px; }

h4 { font-size: 16px; }

h5 { font-size: 14px; }

h6 { color: #777; font-size: 14px; }

body>h2:first-child, body>h1:first-child, body>h1:first-child+h2, body>h3:first-child, body>h4:first-child, body>h5:first-child, body>h6:first-child { margin-top: 0; padding-top: 0; }

a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 { margin-top: 0; padding-top: 0; }

h1+p, h2+p, h3+p, h4+p, h5+p, h6+p { margin-top: 10px; }

/* LINKS =============================================================================*/

a { color: #4183C4; text-decoration: none; }

a:hover { text-decoration: underline; }

/* LISTS =============================================================================*/

ul, ol { padding-left: 30px; }

ul li > :first-child, ol li > :first-child, ul li ul:first-of-type, ol li ol:first-of-type, ul li ol:first-of-type, ol li ul:first-of-type { margin-top: 0px; }

ul ul, ul ol, ol ol, ol ul { margin-bottom: 0; }

dl { padding: 0; }

dl dt { font-size: 14px; font-weight: bold; font-style: italic; padding: 0; margin: 15px 0 5px; }

dl dt:first-child { padding: 0; }

dl dt>:first-child { margin-top: 0px; }

dl dt>:last-child { margin-bottom: 0px; }

dl dd { margin: 0 0 15px; padding: 0 15px; }

dl dd>:first-child { margin-top: 0px; }

dl dd>:last-child { margin-bottom: 0px; }

/* CODE =============================================================================*/

pre, code, tt { font-size: 12px; font-family: Consolas, "Liberation Mono", Courier, monospace; }

code, tt { margin: 0 0px; padding: 0px 0px; white-space: nowrap; border: 1px solid #eaeaea; background-color: #f8f8f8; border-radius: 3px; }

pre>code { margin: 0; padding: 0; white-space: pre; border: none; background: transparent; }

pre { background-color: #f8f8f8; border: 1px solid #ccc; font-size: 13px; line-height: 19px; overflow: auto; padding: 6px 10px; border-radius: 3px; }

pre code, pre tt { background-color: transparent; border: none; }

kbd { -moz-border-bottom-colors: none; -moz-border-left-colors: none; -moz-border-right-colors: none; -moz-border-top-colors: none; background-color: #DDDDDD; background-image: linear-gradient(#F1F1F1, #DDDDDD); background-repeat: repeat-x; border-color: #DDDDDD #CCCCCC #CCCCCC #DDDDDD; border-image: none; border-radius: 2px 2px 2px 2px; border-style: solid; border-width: 1px; font-family: "Helvetica Neue",Helvetica,Arial,sans-serif; line-height: 10px; padding: 1px 4px; }

/* QUOTES =============================================================================*/

blockquote { border-left: 4px solid #DDD; padding: 0 15px; color: #777; }

blockquote>:first-child { margin-top: 0px; }

blockquote>:last-child { margin-bottom: 0px; }

/* HORIZONTAL RULES =============================================================================*/

hr { clear: both; margin: 15px 0; height: 0px; overflow: hidden; border: none; background: transparent; border-bottom: 4px solid #ddd; padding: 0; }

/* TABLES =============================================================================*/

table th { font-weight: bold; }

table th, table td { border: 1px solid #ccc; padding: 6px 13px; }

table tr { border-top: 1px solid #ccc; background-color: #fff; }

table tr:nth-child(2n) { background-color: #f8f8f8; }

/* IMAGES =============================================================================*/

img { max-width: 100% } </style>

Introduction

This is a basic guide to using Git for T3D contribution and development.
This guide assumes you already have installed git and it is integrated into your console. To test that this is the case, open up a command-line window (windows key + r -> type in "cmd" without the quotes -> press enter) and write

git

And then press enter, if it says the command was not recognized, then you probably haven't set Git up properly.

Platform
This tutorial is aimed towards Windows developers, but I don't see why it wouldn't work for Linux or Mac as well, aside from minor differences in terminology.

Getting the code

Cloning vs. Forking

When should you fork and when should you clone?
Cloning
Cloning is when you need a local copy of a remote repository. You should not clone if your intention is to push your changes to a remote repository.
Forking
Forking is for when you need to create copy of the repository on GitHub, which you can make changes to and merge those changes in to the official repository.

Cloning

Cloning a repository is really easy. First open a command-line window, and navigate to the parent repository of where you want your repository to be downloaded to. (e.g. C:/Users/Lukas/My Documents/GitHub).

CMD

Then you write: git clone repositoryURL where repositoryURL is the URL for the .git repository on GitHub, for Torque3D it is:

git clone https://github.com/GarageGames/Torque3D.git

The command in the window looks like this:

Clone T3D

Just press enter, and you are done! It will now clone the repository into a new folder called "Torque3D".

Forking

Forking a repository is simple as well. When you want to fork a repository, you do it over the GitHub website.
Simply go to https://github.com/GarageGames/Torque3D and press the "fork" button.

Fork

And now just clone your forked repository, which you can find at github.com/(your GitHub username)/Torque3D
For example mine is located at https://github.com/lukaspj/Torque3D.

To get a local copy of your repository you will have to clone it as explained earlier, except this time you shouldn't use the URL for the Torque3D repository but instead the URL for your own repository, which you can find by going to your repository on GitHub.com and find the box that says: "HTTPS clone URL" and copy the link inside that box.

Clone URL

For me it is:

https://github.com/lukaspj/Torque3D.git

Contributing

If you want to contribute bug-fixes or other code to the T3D repository, then you should be familiar with the procedure for doing this.
The general "Contribution" workflow I use is whenever I there is something I want to change (e.g. a bug-fix) is:

  1. Create a new branch for the change
  2. Checkout that branch
  3. Make the changes
  4. Add the changes
  5. Commit the changes
  6. Push the changes to my own repo on GitHub
  7. PullRequest the changes to the official repo

So lets go through this procedure step-by-step.

Branches

Branches are basically different versions of the same base code. When you create a new branch, you can edit it all you want, then checkout master and nothing will have changed.
It is good practice to create a branch for even the smallest change you make, this makes it easy to track, and undo changes if an issue arises later on.

Creating a branch
Creating a branch is very simple, just write

git branch new_branchname

Where new_branchname should be replaced by the name of the new branch you want to create.

Changing the current branch
When you want to change the branch you are currently working on you use the checkout command, it's very simple:

git checkout branchname

Where branchname should be replaced by the name of the branch you want to start working on.

Upstream
We need to tell our new branch where it should push any commits you've made to. We do this by using the --set-upstream modifier on the push command:

git push --set-upstream origin remote_branchname

Where remote_branchname should be replaced by the branch on the remote repository you want to push to (typically this will be the same branchname as your current branch, if you use the same branch name then GitHub will usually create that branch for you automatically.

Now you just need to make the changes to the code! Fix the bug, add the feature, whatever your intention with the branch was.

Committing

When you are done modifying the code, you need to commit the changes before pushing them.
First you need to add the files you want to commit, you do this with the git add command:

git add newfile.txt

The add command uses wildcards so you don't have to type in every file you want committed:

git add * // Adds everything
git add *.txt // Adds all .txt files
git add *foo.txt // Adds all files ending with foo.txt
git add foo.txt // Adds foo.txt

Committing
Now that you have added the files, you can now commit them by using the commit command.

git commit

This will add all the files you have changed to a new commit, you can use the -m modifier if you only have a short commit message which you can write directly in the console.

git commit -m "Commit message"

Pushing
Now that you have committed your changes, you should now push them to the online repository. For this you will use the push command:

git push

It may ask you for a username and password, for this just use the same username and password as you use for GitHub.com

Summary

git branch NewFeature
git checkout NewFeature
git push --set-upstream origin NewFeature
// Make the changes
git add *
git commit -m "Wow new feature that does this"
git push

Pullrequests

Assuming you have successfully pushed the commit to the online repository, you should now be able to do a pullrequest. Pullrequests are done through the website, and are very simple to perform.
Go to your online repository and press the green Compare and review button.

Pullrequest

Now you come to the compare page, on this page you can compare your repository with the official one and create pullrequests from a branch in your repository to a branch in the official one.

You can edit what branches and repositories you want to compare by clicking the "Edit" button

compare

And you can see what changes has been made below that bar:

Now to actually make the PullRequest, click on the large button that says "Click to create a pull request for this comparison"

The dialog that then pops up will feature a title and a description. Here you should describe all the commits that your pull request involves! (If you only have 1 commit, copy-pasting the information from that commit will be fine) along with a "how to use" (or "how to replicate the bug this PullRequest fixes"). Then you just press "Send pull request" and thats it! Now you just have to wait untill the PullRequest is accepted/rejected and act accordingly. Be sure to be ready to help out if there is some issues with the PullRequest.
Make sure to checkout the guidelines below.

Important guidelines for contributing

Always pullrequest to the development branch
New changes should always go into the development branch before they go into the master branch, this is because they need to be QA'd before going into the Master branch. If you don't pullrequest to the development branch, your pullrequest will be rejected.

Avoid redundancy
If you have a branch this fixes feature "x" make sure that, that is all it does. Don't do a pullrequest that does anything else than what it says on the label. If there is a bunch of redundant changes in the branch, it will make it hard to track those changes later on since it's hidden under another pull request. So most likely your pullrequest will be rejected if this is the case.

Keep the amount of commits to a minimum
If you have a commit that fixes the issue, and then 5 commits to fix various mistakes / typos, you will be better off removing all the commits and then do a new commit, this will be much cleaner and easier to manage. You can look at the Troubleshooting section for how to remove a range of commits.

Write meaningful commit messages
No one can figure out what "newcommit" changes, and no one can track the change if an issue arises with it. Take your time to write a short but complete commit description such as:

Improved performance in Player::update when the player stands on a chicken

Troubleshooting

This is general quality-of-life hacks that I have found very useful, I cannot guarantee that this is the 'official' way to do it, but for me it works.

Getting the id of a commit

You can use git log to find a list of all the commits ever made to the repository, you will see something like this:

commit 8ee943d9ba2a2856662fe1c7e5d6747794db2585
Merge: be32424 71d4082
Author: Lukas Joergensen <ljorgensen@winterleafentertainment.com>
Date:   Thu Sep 5 12:31:46 2013 -0700

Merge pull request #1 from lukaspj/SideCamera

Basic side camera



commit 71d4082810c4a26b8f4ee0cae44db18843d082d2
Author: Lukas Jørgensen <ljorgensen@winterleafentertainment.com>
Date:   Thu Sep 5 21:29:32 2013 +0200


Fixed untracked files</code></pre>



It's that long string of numbers and characters that makes up the id of the commit.




commit 8ee943d9ba2a2856662fe1c7e5d6747794db2585




Resetting your repository to an earlier state


If you have made a mistake and want to undo the changes made in a commit you will use the git reset command.
E.g.


git reset --soft 8ee943d9ba2a2856662fe1c7e5d6747794db2585


Notice how I used --soft here, there are 5 different modifiers, whereas I've only ever used 2, so to keep it simple I will only talk about those two:
--soft
This modifier resets the repository to an earlier stage, but does not undo changes to the files but instead marks them as "to-be-committed".


--hard
This modifier resets the repository to an earlier stage AND undoes all changes made to the files.


There is also some shortcuts to refer to earlier commits:


git reset --soft HEAD     // Resets the branch to current commit
git reset --soft HEAD~     // Resets the branch to the commit just before the current one
git reset --soft HEAD~2    // Resets the branch to the 3rd newest commit
git reset --soft HEAD~3    // Resets the branch to the 4th newest commit
// And so on..


So basically it goes:


HEAD->HEAD~->HEAD~2->HEAD~3->...->HEAD~n


(if you have a branch merged with the branch you are working on it gets a little more complicated than that, but I will assume you wont have a branch merged with your working branch)


Remove a range of commits


If you want to remove the commits themselves and not just revert the repository to an earlier stage (e.g. to make a clean PullRequest with just 1 commit), then you will use git rebase -i.
E.g.


git rebase -i HEAD~2


This will open up a text editor with options for what to do with each commit, if there is some commits you want to merge together, use the "squash" option to merge them together.
E.g.




pick 358412f New readme for v2.0
pick 4b644e4 Elastic ease fix




Change this to:




pick 358412f New readme for v2.0
squash 4b644e4 Elastic ease fix




To make the Elastic ease fix commit be merged into the previous commit, New readme for v2.0.
Add a custom footer
Add a custom sidebar
Clone this wiki locally