How to create a pull request using TortoiseHG

Discussion area about developing or extending OGRE, adding plugins for it or building applications on it. No newbie questions please, use the Help forum for that.
Post Reply
User avatar
KungFooMasta
OGRE Contributor
OGRE Contributor
Posts: 2087
Joined: Thu Mar 03, 2005 7:11 am
Location: WA, USA
x 16
Contact:

How to create a pull request using TortoiseHG

Post by KungFooMasta »

Hi community,

Sorry for the newbie question. I'm reading through the TortoiseHG online documentation, as well as Ogre's guidelines for submitting a patch, however its not clear to me how I can "create a pull request" as specified in the Ogre guidelines.

I believe I have my changes committed to my local repository. By the way what is the difference between "default", "v1-9", and "v2-0"? I am working in the "default", and the only option I can think of to use is the "Push outgoing changes to https://bitbucket.org/sinbad/ogre" button, however I get the error message
abort: push creates new remote head
Sorry again, I'm sure this seems brain dead easy for most of you. At the moment I'm just trying to patch up a small part of the D3D11 render system so that it doesn't crash when loading in the WinRT desktop simulator with VS2013.
Creator of QuickGUI!
User avatar
spacegaier
OGRE Team Member
OGRE Team Member
Posts: 4304
Joined: Mon Feb 04, 2008 2:02 pm
Location: Germany
x 135
Contact:

Re: How to create a pull request using TortoiseHG

Post by spacegaier »

v1-9: The currently stable and released Ogre version
default: The current bleeding edge = development version (the future v1-10)
v2-0: The planned major revision with many API-breaking changes and huge performance increase thanks to heavy optimization and redesign

Pull-requests work with forks. So you first need to create your own fork of the Ogre3D repository on BitBucket, implement your changes in your local fork clone and then push them to the remote one. Afterwards, you can create the pull-requests from your remote fork to the official code base on BitBucket directly.

From the sound of it, you are currently trying to directly change the code inside the official repository (https://bitbucket.org/sinbad/ogre), for which you most likely do not have authorization. Additionally, as Hg is telling you, you would create a second head which always has to be avoided. Therefore, always pull in the latest changes into your local repository and execute a merge between those and your local changes (this automatic pull before push can also be configured in same GUI versions, such TortoiseHg). Only then can you safely push your changes.

Additionally, pay attention to that guide: http://www.ogre3d.org/forums/viewtopic. ... 86#p503286
Ogre Admin [Admin, Dev, PR, Finance, Wiki, etc.] | BasicOgreFramework | AdvancedOgreFramework
Don't know what to do in your spare time? Help the Ogre wiki grow! Or squash a bug...
User avatar
KungFooMasta
OGRE Contributor
OGRE Contributor
Posts: 2087
Joined: Thu Mar 03, 2005 7:11 am
Location: WA, USA
x 16
Contact:

Re: How to create a pull request using TortoiseHG

Post by KungFooMasta »

ok so I created a bitbucket account, and forked the repository, I now have https://bitbucket.org/KungFooMasta/ogre.

I created a patch from my old cloned repository, 6286.patch, however when I try to import this patch into my new repository, I get failures:
% hg import --verbose -- "D:\Sandbox\Ogre\6286.patch"
applying D:\Sandbox\Ogre\6286.patch
patching file .hgignore
patching file OgreMain/src/WIN32/OgreErrorDialogWinRT.cpp
Hunk #1 FAILED at 28
1 out of 1 hunks FAILED -- saving rejects to file OgreMain/src/WIN32/OgreErrorDialogWinRT.cpp.rej
patching file RenderSystems/Direct3D11/src/OgreD3D11VideoModeList.cpp
Hunk #1 FAILED at 76
1 out of 1 hunks FAILED -- saving rejects to file RenderSystems/Direct3D11/src/OgreD3D11VideoModeList.cpp.rej
abort: patch failed to apply
[command returned code 255 Fri Feb 28 14:04:30 2014]
it doesn't tell me whay these hunks have failed. I don't know if this is relevant by I previously cloned https://bitbucket.org/sinbad/ogre to D:\Sandbox\Ogre, and now that I needed to fork and work on that, I renamed D:\Sandbox\Ogre to D:\Sandbox\Ogre_Sinbad, and created D:\Sandbox\Ogre and used that to clone my forked repository.

Is it possible Mercurial is quite a bit more complex to use compared to SVN? I remember TortoiseSVN being very easy to use for my personal projects. TortoiseHg feels like it has so many options, pulling, pushing, commit, import, export, tip, working directory.. the "task" approach they're using doesn't seem to help me accomplish any tasks.. :lol:
Creator of QuickGUI!
User avatar
spacegaier
OGRE Team Member
OGRE Team Member
Posts: 4304
Joined: Mon Feb 04, 2008 2:02 pm
Location: Germany
x 135
Contact:

Re: How to create a pull request using TortoiseHG

Post by spacegaier »

Have a look at those *.rej files. They will tell you what couldn't be merged / patched.

Regarding your process: One reason for your troubles could be that your previous local clone of the main repository was not up-to-date. Your new local clone of your fork however is. Since all Hg commits are relative/linked to its parent/previous commit, that might be where the merge/patch conflicts are stemming from. If nothing else helps, copy your code changes over manually into your new fork.

Overall: After a little bit of getting used to, TortoiseHg (or Mercurial in general for that matter) feels quite good.
Ogre Admin [Admin, Dev, PR, Finance, Wiki, etc.] | BasicOgreFramework | AdvancedOgreFramework
Don't know what to do in your spare time? Help the Ogre wiki grow! Or squash a bug...
User avatar
dark_sylinc
OGRE Team Member
OGRE Team Member
Posts: 5296
Joined: Sat Jul 21, 2007 4:55 pm
Location: Buenos Aires, Argentina
x 1278
Contact:

Re: How to create a pull request using TortoiseHG

Post by dark_sylinc »

Welcome back KungFooMasta! haven't seen you in a while!

As an old timer SVN user that learned to love Hg after roughly half a year of swearing:

In SVN you're used to have "one timeline" (the history log). You checkout, and commit. If there were changes, you may have to merge or even resolve conflicts after the checkout and before the commit.
The big disadvantage of this model is that you risk losing your changes if you make a mistake while merging. Additionally, if you're working on a particular feature that isn't ready yet, you can't commit otherwise you'll break everything for everybody.

In Hg... you have "multiple timelines" think of them as parallel universes. You made a change, then commit. Now you pull other timelines. Someone made changes. Let's call him Bob. So there are two different timelines: yours and Bob's. This is known as having two heads. You made one commit, Bob made also one commit. But both have the same parent.
Your first instinct will be to collapse both timelines into one. So that they look like one (and will appear cleaner, more SVN like). Either Bob's commit should come before yours, or yours should come before Bob's. DON'T. You can try to do this using patches or the rebase extensions. But stop fighting it. Hg is not meant to work like that.

Instead, you have to make a third commit: In this commit, both timelines will merge into one, and you'll have the chance of resolving the conflicts. Graphically, the log looks like a street that gets split in two and then joins back. May look ugly to you at first, but you'll get used to it and at some point wonder how you couldn't live without it (it has a lot of small advantages).

Now, patches usually fail at merges since they can't handle it very well, so that "HUNK failed" is probably that. There must be a merge in the middle of your patch.

Something that saves you a lot of time that wasn't obvious to me: When you want (i.e.) to merge two commits, you have to update to one of the commits, and then select the other commit that will be merged into the current active one. i.e. You can't be using commit C, and select A & B so they get merged as 'D'. You first have to be using either 'A' or 'B', and select the other one to start the merge.
KungFooMasta wrote:Is it possible Mercurial is quite a bit more complex to use compared to SVN? I remember TortoiseSVN being very easy to use for my personal projects. TortoiseHg feels like it has so many options, pulling, pushing, commit, import, export, tip, working directory.. the "task" approach they're using doesn't seem to help me accomplish any tasks.. :lol:
At first it's overwhelming:
  • pulling: Grab the other timelines (alternate universes!) that were pushed by everyone else
  • pushing: Send your timeline's changes so that everyone else sees them and can pull them
  • Commit: Commit
  • Import / Export: Don't use this. They have a few uses. But seriously, for now forget them.
  • Tip: useless jargon (it's the last commit that was pushed)
  • Heads: How many alternate timelines there are that weren't merged. Public repos should avoid having more than one head, because there is no "true" choice. Both could be working. In your universe, D3D11 was improved. In Bob's universe D3D9 was improved. Which one is correct? Both! So if they merge, they'll create a single timeline again where both D3D9 & D3D11 are improved.
Everyone's workflow is this: Commit, Push, Merge, Pull.
The reason you see more options is when you want to start manipulating the history. Which is always nasty unfortunately. But that's a maintainer's job.

When you create a fork, you create an online clone of Ogre but where you have write access. You then commit your changes, push them. And then through a pull request... you request our repo to pull your changes and merge them.

The problem with SVN was that if you had changed 10 files, and Bob changed them too, then there was a high chance for you to screw up when you merge during your commit and end up with a broken repo (or worse, a repo that compiles but now manifests a bug that wasn't in Bob's version nor in yours).
In Hg, we can check that the bug doesn't manifest in your parallel universe nor in Bob's, but it does manifest after the merge. Thus we'll be able to identify that it wasn't your changes nor Bob's, but rather the merge process.

There are also other benefits: you can make multiple commits without having to worry about merging for a while, or commit even if internet is gone.

The disadvantage is that once you've pushed your changes, stripping them if you made a mistake is as easy as asking every torrent pirate to delete their mp4 video they obtained illegaly (practically unfeasable!). If you commit a 0.5GB file by accident and push it, God save us all (unless you're quick enough to strip it before anyone pulls, or agree with everyone to strip them from their repo as well).

Also, since there are parallel universes, revision numbers don't really make sense outside the local repo: To Bob, his commit was made first. Then when he pulled, he saw your changes and your merge. Bob's could be rev 2000, yours 2001, and the merge 2002.
To you however, your changes came first: Yours is 2000, Bob's is 2001, and the merge 2002.
This is why commits are best referred to using their hash (which is unique and the same for everyone)
User avatar
dark_sylinc
OGRE Team Member
OGRE Team Member
Posts: 5296
Joined: Sat Jul 21, 2007 4:55 pm
Location: Buenos Aires, Argentina
x 1278
Contact:

Re: How to create a pull request using TortoiseHG

Post by dark_sylinc »

As for your problem
KungFooMasta wrote: I created a patch from my old cloned repository, 6286.patch, however when I try to import this patch into my new repository, I get failures:
Nah, don't do that.
Instead open the Synchronize section in TortoiseHg Workbench (Alt+7) and put the path of your old repo. Now click the pull button. The changes from the old repo will be incoroporated to your new repo.
You'll probably end up with two heads, so you'll have to merge them.

Also, watch out if your old or new repo has the EOL problem. That was a problem I made. My bad. I screwed up big time.
If none of your repos have the commits "dad316a675428a66c24e5dc6f0e6b7abb6d5d7d1" & "81746916438203c5dfc06177d8eb91e84d4f50f3" then your repos are ok (you can search them hitting Ctrl+S)
User avatar
KungFooMasta
OGRE Contributor
OGRE Contributor
Posts: 2087
Joined: Thu Mar 03, 2005 7:11 am
Location: WA, USA
x 16
Contact:

Re: How to create a pull request using TortoiseHG

Post by KungFooMasta »

Wow, thanks dark_sylinc! It has been a while. :D

Thanks for taking the time to explain things. Hopefully it will start to catch on.

I noticed that the change list numbers were quite different between my local Ogre_sinbad repository (bitbucket.org/Sinbad/Ogre) and my new Ogre repository (bitbucket.org/KungFooMasta/ogre)

Alt+7 didn't bring up anything for me, but I think I found the Synchronize tab, and from that I saw an option to "Check for incoming changes from selected URL" and "Pull incoming changes from selected URL". I did both of those in the order I listed, and output said "Pull from https://bitbucket.org/sinbad/ogre/ completed". (trying to get my forked repo up to date)

In the history tracking tab at the very top it says my "Working Directory" has changelist number "5837+", does this seem like the latest for "default"? I see v1-9 branches with changelists up to 6279. It seems odd to me that default is lower than v1-9, but I'm guessing it means more changes are going into v1-9 as opposed to default.. right?

What is the process to merge? Do I select a particular change (row) and from right click menu use the "Merge with local..." option? The visual graph looks like a straight line, so maybe I don't have anything to merge..
Creator of QuickGUI!
Post Reply