How to use SourceTree and GitHub to send your FP modifications (Pull Requests)

(Martí Angelats i Ribera) #1

Hello everyone

This tutorial tries to allow anyone to make a pull request to any GitHub repository (for obvious reasons this one is focused on FlashPunk).

##Before start Don’t make a pull request without any reason or “just for testing” (of course if you improve something you should do it). This throws other people time.

This tutorial was made using Windows and SourceTree. For Mac users should be the same (SourceTree have Mac version) but i’m not 100% sure.

SourceTree also supports other plataforms (like Bitbucket) but the steps to follow can be slightly differents.

##The tutorial itself Follow the steps to do it.

####1. Create a GitHub account Pretty self explanatory (if you have it skip it for ovious reasons).

####2. Download, install and setup SourceTree

  1. Here the download link.
  2. Install it.
  3. Add your GitHub account username and password when the program asks it to you.

####3. Fork the github project

  1. Go to GitHub web page and log in.
  2. Go to the FlashPunk GitHub project page (click here).
  3. Fork the repostery (click the button wich is on the top right) (see image).

####4. Clone the repostery to your pc

  1. Go to your forked FlashPunk (if you’re not already there) (be sure it’s the forked one [is YOUR repository]).
  2. Clone the url (copy the url to the clipboard) (see image).
  3. Go to SourceTree and click to Clone/New.
  4. The first text field (Source Path / URL) paste the URL.
  5. Choose where you will save your project (Destination Path) (There will be all the project andall the versions you make).
  6. Choose a name (this is only as a bookmark. I recomend to use “FlashPunk” or “FP” but you can choose any name).
  7. Click that Clone button.

####5. Work with it! This is part is a bit different becouse you’ll repet some thing every time you want to work. It’s not a liniar instructions to follow but it’s easy to understand (I’ll say how to make it later on).

Things you have to know what they mean:

  • Pull: It basically updates your local version to the one it’s in the cloud.

  • Commit: Groups all the changes you want and allow you to define them (reasons, changes, etc.). This comentary is not necesary but it helps a lot to see the history line and the different modifications that have been done (if anything that was right fails, you can return to an older state).

  • Push: Update the cloud and apply your commited (and only the commited) changes.

  • Pull Request: This can’t be made using the SourceTree and have to be done using the web. The modifications you did using a Push will only effect your repository. A Pull request “asks” to the owner of the forked project (in this case FP) to modify the main repository with your changes.

Alright, we’re almost done. Now let’s do the modifications.

  1. Go to SourceTree.
  2. If it’s not opened, open the cloned repository.
  3. Hit that Pull button to pull your repository (at the top) and click OK.
  4. Now you have the project so go to the folder you gived and modify whatever you want (you can use external programs).
  5. Commit (this have more than one step):
  6. Go to the File Status (probably you’re there) and use the arrows to move the modified files to the stage, at the top, (you probably want them all) (see image). The double arrow will move all the files.
  7. Click Commit and add the message you want.
  8. Push your modifications (only have to click that Push button and the OK)
  9. Go to your GitHub forked repository.
  10. Click this green button (image), then click to Compare between forks and finally the Create Pull Request.
  11. To finish you have to write all the information they need to see what you’ve modified and why and send it.

Now you’ll have to wait untill they accept it or refuse it (they can also send you a message asking for something but it’s not common for small changes). Any activity will make GitHub to send you an email.

####6. More changes? If you have to fork another project go to part 3 and continue but in the other project insted of FP.

If you want to make more changes to FP, you will have to go to the part 5 and repeat it. You don’t need to Pull unless there’s someone else modifying the project (becouse you’ll already have the last version in your Hard Drive.

###Help me to improve it This can contain errors. If you find any error or posible missunderstanding sentence just say it (if you want you can send me a private message or comment here).

Also if you have an idea to improve it let me know it.

PD: Special thanks to @miguelmurca for being the first to try it and corrected an small error.

(Zachary Lewis) #2

What’s the benefit of SourceTree as opposed to the GitHub client?

GitHub also has excellent guides if you want to use their client.

(Martí Angelats i Ribera) #3

I did the tutorial with SourceTree becouse is the program i use.

The GitHub client allow to do things that SourceTree can’t (you have to use your web bowser) but it only works for GitHub (SourceTree allows you to have more repositories from other platforms like Bitbucket and it works identically [same GUI]).

(Royston) #4

Hi, there’s a typo in the text, “liniar” should be “linear”.