Howto: Maintain A Remote Fork For Pull Requests (Tortoisegit)

[bootz]

Project SkyFire now uses pull requests instead of raw patches for submitting changes. This makes it easier for the devs. to review the code and talk to the patch creator (inline on github) before merging into the source.

The purpose of this guide is to help those who may not be familiar with the process. It will show you how to:

• Create a remote fork
• Push a patch to your remote fork
• Create a pull request
• Keep your remote fork up-to-date with the main repo

This guide will cover the use of TortoiseGIT on Windows XP (should be similar for other Windows versions). All of the procedures can be done via the GIT commandline which I may write a tutorial for soon â„¢.

Requirements:

• GIT
• An account on github.com
• TortoiseGIT
• Windows (I know, I know.. eww!)
• A web browser

I. Fork the main repo

This provides you with a personal copy of the repo for submitting pull requests

• 1. Open your browser and go to the main SkyFireEMU repo
• 2. Click the 'create fork' button

II. Clone the fork to your local PC

This will allow you to create branches and patches. We will refer to this as your 'local repo'.

• 1. Open your browser to your fork you made in step I
• 2. Click HTTP (or ssh if available) and copy the URL in the box
• 3. Create a folder on your harddrive (give it a meaningful name)
• 4. Right-click in the folder from step 3 and choose: 'TortoiseGIT->Clone'
• 5. Paste the URL you copied from step 2 into the 'URL' box and click 'OK'

III. Create a reference to the remote master

This will allow you to keep your fork up-to-date with the master

• 1. Right-click on your local repo and select 'TortoiseGIT->Synch...'
• 2. Click 'Manage' next to the 'Remote URL' box
• 3. Fill in the remote info for the master you cloned:
  • 3a. Name: Anything you want
  • 3b. URL: The URL of the master you cloned from I.1
  • 3c. click 'OK'
• 4. Close the main dialog, we will use it later

IV. Synchronizing the remote fork with the remote source

This synchronizes your remote fork with the remote SkyFireEMU master.

You should do this before starting a new branch / patch.

• 1. Switch your local repo to its master branch
  • 1a. Right-click on your local repo and select 'TortoiseGIT->Switch/Checkout...'
  • 1b. Choose 'master' and click 'OK'
• 2. Right-click on your local repo and select 'TortoiseGIT->Sync...'
• 3. Make sure both 'local branch' and 'remote branch' say 'master'
• 4. Select the reference to the remote master you made in step III for 'Remote URL'
  • * Choosing 'origin' here would just pull your fork again
• 5. Click 'Pull'
• 6. Click 'OK'
• 7. Right-click on your local repo and select 'TortoiseGIT -> Push...'
• 8. Make sure both 'local branch' and 'remote branch' say 'master'
• 9. Select 'origin' for 'Remote URL'
  • * Origin should point to the fork you made in step I
• 10. Click 'OK'

V. Creating a local branch

This allows you to keep track of the patches you're working on.

You should synchronize your repo before starting (see step IV).

• 1. Right-click on your local repo and select 'TortoiseGIT->Create Branch...'
• 2. Give the branch a unique name
• 3. Select which branch to base it on (usually master)
• 4. Click 'OK'

• * Optionally select "switch to branch" if you plan to work in it

VI. Creating a patch and pushing it

This allows you to push your patch to your remote fork, preparing for a pull request

Always synchronize (see step IV) with the TrinityCore master and create a new branch (see step V)

BEFORE starting a new patch

Please note, if you receive password prompts when trying to push to your repo, review the documents on

github regarding SSH Keys: Setup GIT (scroll down to 'Set Up SSH Keys') and SSH issues

• 1. Switch to the desired branch if not already in it:
  • 1a. Right-click on your local repo and select 'TortoiseGIT->Switch/Checkout...'
  • 1b. Choose the branch and click 'OK'
• 2. Make your changes
  • Compile and test your patch
• 3. Push the changes to the local repo (if everything compiled / tested OK)
  • 3a. Right-click on your local repo and select 'TortoiseGIT->Commit->'
    • * This will show the name of the current branch
  • 3b. Enter a comment and click 'OK'
    • * If your patch closes an issue on Github, using the issue number with

      a '#' should create a clickable link to the original issue when you push to your fork.

    • example: closes #5637
• 4. Push the changes to the remote fork
  • 4a. Right-click on your local repo and select 'TortoiseGIT->Push...'
  • 4b. Fill in the information under the 'Branch' group
    • Local: <select the branch you're interested in>
    • Remote: <enter the same name as the local branch>
    • * This will force creation of the remote branch
  • 4c. Fill in the information under 'Destination'
    • Remote: <select the remote you're pushing to>
    • * This should be your fork which is typically 'origin'
  • 4d. Click 'OK'

VII. Creating a pull request

This lets the developers know you've got some code to review

Always compile and test before submitting a pull request

• 1. Open your browser to your fork you made in step I
• 2. Click the button that says 'branch: master'
  • * It may not say 'master' if you were browsing another branch
• 3. Select the branch you just pushed in step VI
• 4. Click the 'pull request' button (not the 'pull requests' button)
• 5. Enter something descriptive and submit your request

Final notes:

This may seem a bit daunting but after you've done it a few times it's pretty simple. The most involved part is synchronizing your fork with SkyFireEMU because of the interim step of sucking it down to your harddrive first.

It is important to remember to:

• Always synchronize with the SkyFireEMU master and create a new branch BEFORE

  starting a new patch

  .
• Always compile and test your patches before submitting a pull request

You can repeat steps IV to VII as often as you want. Just remember it is easier to work on each patch in a separate branch. That way you won't contaminate your work with unrelated, unnecessary changes.

Finally, if you feel like it, you can delete your fork via github but make sure your pull request has been merged first or your changes will be lost.

Edit1: Clarify a few things and add links to Git for information on SSH (step VI).

Edit2: Added emphasis on compiling and testing

Edit3: Fix typo (spacing)

This Migrated from over @ TrinityCore's forums and some lite adjustments made for us,

to set the same "Patching and PR" rules as they have...


Explanation for the change...



The reason for this? you ask, that's simple...

many people just don't have any idea on how to

make a proper .diff patch.

and its extremely time consuming for the Devs to have watch

every thread or topic, not to mention, when we have to

figure-out the patch (deciphering it), b4 we can even move

to test it and all that.


that brings me to the other reason,

many of the Communities sub-forums much like this one,

has way too many inactive/dead threads,

hopefully soon to be archived.

and would be nice to have a couple mods, to keep

the threads cleared, and so you as a community member,

won't have to swim through a sea of old patch works,

and have to wonder if, its an old thread or active.

or why "that guy" cant seem to post in the right areas 

anyways...

this sub-section will remain open for community developments

for patches, "If" or "When" your project thread has a finished,

(ready to submit) please Pull-Request it. and leave message to

mods to close thread, as to reduce the forums clutter 


~thanks guys.


we'll have someone go through eventually and update mr.smites walk through.

if any issues or miss understandings with this, please use our irc.

there's usually someone online that can be of assistance