Jump to content
TrinityCore
MrSmite

[HowTo] Maintain a remote fork for pull requests (TortoiseGIT)

Recommended Posts

Preface:

 

You're not seeing double, this guide is the same as the one that was pinned for over a year with over 5k views. It was recently merged into a topic about the GIT commandline which I personally feel was not the right place for it.

 

This guide is specifically for people who use TortoiseGIT and want to write patches. It's easier to ask and answer questions in its own topic without the clutter of the commandline discussion, not to mention find it using the search tool.

 

Technically it belongs on the wiki but for now this will do.

 

The Guide:

 

TrinityCore 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:

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 TrinityCore 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
    • As of 2013-11-01 Github has changed its layout. There is a "Clone URL" box on the right side of the page. Click either HTTPS or SSH to toggle between the two and copy the desired URL from 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 this reference later

IV. Synchronizing the remote fork with the remote source

This synchronizes your remote fork with the remote TrinityCore 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 TrinityCore because of the interim step of sucking it down to your harddrive first.

It is important to remember to:

  • Always synchronize with the TrinityCore 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)
Edit4: More clarifications

 

Share this post


Link to post
Share on other sites

Pinned.

I, for one, didn't like the merge, I think each guide must be in a separate topic as long as they cover separate aspects of a problem.

  • Upvote 3

Share this post


Link to post
Share on other sites

Shouldn't rebasing be a requirement as well before initiating a pull request?

 

No.

 

Since a rebase simply pulls a fresh copy and attempts to merge your changes, it is redundant to what you did in the guide (pull a fresh copy before starting work). Once you submit your PR it could end up sitting for a long time before anyone attempts to merge it and it would most likely fail at that point anyway.

 

A rebase before pull request would only be useful if it were guaranteed that a developer would review and merge your changes within a timely fashion.

Share this post


Link to post
Share on other sites

Can I do the same procedures using only git or git extensions? I mean, without TortoiseGIT installed (how?)

What about Github for Windows?

Edited by Frondor

Share this post


Link to post
Share on other sites

All these graphical interfaces run on top of Git. Everything can be done with Git alone.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.

×