Making Pull Requests on Hercules

[jaBote 438]

Do you remember the many advantages Git has against Subversion (SVN)? One of those many advantages is the fact that in Git, you can send pull requests in order to directly collaborate with the community, without even the need of being an official Hercules dev, and if you contribute enough you can surely become a dev if you want. Well then, this is an – as detailed as possible – guide on how to make them.
 
First of all: What is a pull request? It's a way of telling the original devs of a (commonly open-sourced) project what changes you've made yourself on their project supposedly for the better, and kindly ask them (request) to merge it (pull). In short, it's a way of collaborating to a project without the need of being related at all to it. Obviously, your pull request may be rejected if it doesn't meet some requirements, but this is another story.
 
Git does also offer its own tools for pull requests (more info), but they're incompatible with the ones GitHub has. Moreover, GitHub pull request tools are easier to use than Git's.
 
What steps are required in order to do a pull request? In abstract, you'll have to:

• Sign up for a GitHub account, if you don't have it already.
• Fork Hercules project in GitHub, if you haven't done this already.
• Clone your previous fork to a local repository in your computer, if you haven't done this already.
• Work on your fork.
• Commit your changes to your local repository.
• Push the changes you've previously committed to your remote repository on GitHub.
• Make the aforementioned pull request to the Hercules official repository.

Steps 3 and 5 have already been shown on the Obtaining Hercules guide by @Ind (Obtaining Hercules through Git on *insert OS here* and Troubleshooting sections). These two steps will be slightly reviewed, but expect a fully detailed how-to in the others.
 
By the way, GitHub also has its own (generic) guides on how to fork a repo and then make a pull request, which also explain the toughest parts of this guide (though they're not so tough) and cover steps 2-6 (supposing you have a Git console). You're encouraged to go and read them if you want.
 
Well, here we go with the guide!
 
Step 1: Sign up for a GitHub account

Well, this is simple. You just need to acces GitHub on your browser and if you don't have an account (or an active session, but if you already have an account just sign in) you'll be greeted by the main page for unregistered users, which has a sign up form. Just fill it out and click on the Sign up for free button. It's free unless you want to open or work for a private repository.
 
You can use fake data for signing up but it's not reccommended. This guide uses a fake account, which will be deleted after its purpose (making a finishing a pull request) is met.
 

 
Now that you're signed up on GitHub you'll be offered some quick guides, including the ones I've previously mentioned. You can read them if you want. From this point onwards I'll suppose you're logged in the GitHub web in order to proceed.

Step 2: Fork Hercules project in GitHub

You now have to fork Hercules in order to make a personal repository for your work. GitHub offers a simple (but yet powerful) tool for forking projects. You just need to go to the original Hercules repository and look on the upper-right buttons. The button you're looking for is a Fork named button and you'll just have to click it. Rest of the process is automated and when it ends you'll be on your own personal Hercules fork repository. Look at the new Pull Request button up there: we'll make use of it later, when you've already pushed changes to this repository.
 

 
Please note your new repository has a very particular name: you're on the Github_user / Hercules repository and its URL is  https://github.com/Github_user/Hercules.git, where Github_user is your GitHub username. You'll be working with this repo, not official Hercules', from this point onwards unless specified.

Steps 3 to 6: Local computer work

Here we have some small steps, all of them are to be done on your computer. You'll Git clone your fork, work on it and commit your changes and then you'll have to push them to your GitHub repository. Don't worry, this isn't much of a hard task. Let's start:

Git clone your forked repository:
After reading (and surely following) @Ind's Obtaining Hercules (through Git on your platform) guide this should be an easy task, don't you think? In case you don't remember how to do that, take a quick look at it: you'll need it.
 
You'll only need to Git clone your fork (not Hercules original repository) on a new folder (remember: its URL is https://github.com/Github_user/Hercules.git where Github_user is your GitHub username as you can see in your fork page). This task is now done.
 
Work in your local repository:
Well, I can't help you here. You'll just have to perform any modifications you deem necessary for collaborating with us. If we knew any modification or improvement to be done for the emulator we wouldn't need your help, isn't it?
 
Just remember to save all files you modified before proceeding with next step.
I've slightly modified doc/script_commands.txt for this guide because I couldn't think of anything better at that moment.

Commit your changes to the local repository:
Once you're done on the emulator, you have to commit your changes to your local repository as just saving them isn't enough – just think of them as a safety measure –. The way of performing the commit depends on the OS you have on wour computer. This has also been explained by @Ind's troubleshooting post, but I'll explain it again as that wasn't part of the main guide.

git commit -am "Commit message. Say cheese :D"

• On Windows:
  • Right click your Hercules fork repository and select the Git Commit -> "master" option.
  • If this is your first time commiting to this repository, you'll probably be asked for a username and e-mail. You can safely provide that info (or even fake them if you want) to TortoiseGit. Just click Yes and fill out Name and Email fields, then click Accept. You don't have to provide a Signing Key ID.
    • Note: If you want to never be asked again (even when working on other repositories or projects) you should check the Save as Global checkbox before accepting or well use Edit global .gitconfig button and then input whatever data you want.
  • A new window will appear, in which you should type a log message (but can left that blank if you want). There are also some other unimportant options unless you know what you are doing). Just click OK and wait for the commit to be finished.
• On Unix: Just run this code from your Hercules fork's local repository directory (edit the commit message if you want):

You can also note that once the commit is made, all modified archives are marked as unchanged. Why? The reason is simple: you've made a new revision only for you (unless you want to make a pull request for it) and right now you're on the latest revision on your fork.

Push local committed changes to our remote GitHub repository:
It's time to push your commit. What does it mean? It's just sending the local commits to the remote repository on GitHub. Otherwise GitHub will never know what we've made on our computer. How to do it? Once again this depends on your OS:

• On Windows:
  • You can do this step by two ways, both with the same result: first one is using the Push... button on the commit window once it's finished. Alternative way is done by right-clicking your repository folder, then select Push... option on the TortoiseGit submenu.
  • You can click OK on the next window unless you know what you're doing. Then push process will start. You'll be asked for your GitHub username and then for your password (if you make a typo you'll get an error and have to try to push again). Once you've been verified you'll be sending your commits to your GitHub repository. Once it's finished, you'll have to close that window because unfortunately, that Create pull request button is useless for GitHub repositories – you'll have to make the pull request on their web instead –.

• On Unix: In this case, you'll just have to run this on your fork's local repository directory:

  git push origin master

  You'll also be asked for your GitHub username and password, just like windows but in the command line interface.

You've successfully pushed your changes to GitHub! You are now encouraged to go and check if your remote repository has received your changes, which will surely do unless you've failed providing your GitHub access credentials when pushing them.

Step 7: (Finally) submitting the pull request

Well, you just need to come back to your fork repository on GitHub. Remember the Pull Request button? It's time to click it. You'll be sent to a page in which you'll have to put a title and a (preferably descriptive) abstract for the changes you're submitting. You shouldn't change anything else unless you know what you're doing. When you're done with all that just click the Send Pull Request green button. You'll be sent back to original Hercules repository to check how your pull request was made. All the rest (accepting/rejecting your pull request and making the pertinent merges) is up to Hercules devs.
 

 

 
Congratulations! You have successfully made your first pull request on Hercules! This is a reason to be proud of yourself, isnt it?

[jaBote 438]

Frequently Asked Questions (FAQs):



I thought splitting this section from the main post would be beneficial because it's easier to write it and to look in it in case you need an answer and I have it down there.



I hope there are almost no questions because I think my guide is clear enough, though it's normal there will be some questions out here since my explanations aren't perfect. That's why this dedicated section exists.



Questions will be marked with a big Q and answers will be marked with a A. Both will be big enough to easily tell them apart.



Question list:

 

• I get a warning message while trying to make a Pull Request on GitHub. What happens?
• How do I update my fork to Hercules' last version?
• I always get an error message whenever I try to push my changes even though I make sure I put correct access credentials. What's happening?
• I can't commit anything to my local repository. What happens?

Questions & Answers:



Q: I get a warning message while trying to make a Pull Request on GitHub. What happens?

A: You can't make a pull request if you get a warning message from GitHub. Those messages usually provide enough information to tell you what to do. Here are all warnings I've received from GitHub to date and its possible solutions – just remember to change HerculesUser to your GitHub username–:

• Oops! HerculesWS:master is already up-to-date with HerculesUser:master Try a different branch?
  • You haven't pushed any changes to your remote repository or the changes you've pushed make it identical to the original Hercules repository. You can only make a pull request if your repository is not exactly the same as the original Hercules'.
• Oops! There's already a pull request for HerculesUser:master Try a different branch or view the pull request?
  • You already have an active pull request on Hercules and you have to wait until it's approved or rejected. If you want to add changes to your pull request, you can push more changes to your repository if you want: they'll automatically be added to your active pull request.

Q: How do I update my fork to Hercules' last version?

A: This is quite simple but not as easy as updating an official Hercules repository as you can't just pull as you did when updating the original Hercules repository – if you try to pull on your fork you're pulling from your fork's repository, not Hercules' –. Doing this task also depends on your OS:

• On Windows: (I don't deem necessary to add a how-to picture for this)
  • Right-click your Hercules fork folder and select Fetch... option from the TortoiseGit submenu.
  • A new window will pop up. Select Arbitrary URL option and place original Hercules repository URL there (I mean this one: https://github.com/HerculesWS/Hercules.git). Then click OK (unless you want to change any of the available options, which is unfrequent) for making the fetch update to start.
  • Another window will be opened and your fork will be updated to Hercules last revision. Close it once you're done.
• On Unix: You just have to run this command (it's actually two commands joint on a single shell statement):

  git fetch upstream && git merge upstream/master

Just remember that if you want these changes to also be on your GitHub repository, you'll have to push them. Otherwise they'll just be available on your local repository, as always.



Q: I always get an error message whenever I try to push my changes even though I make sure I put correct access credentials. What happens?

A: I've just experienced this error when I tried to push to the wrong repository (i.e. the original Hercules repository, to which I don't have access and you surely don't). Make sure you're trying to push to a repository on which you have permission for this. Ah! Also make sure you have an active Internet connection since you'll be using it!



Q: I can't commit anything to my local repository. What happens?

A: Chances are you're trying to make a commit without changing any file, and that's not possible for Git. Maybe you actually changed some files but forgot to save them?

[Brynner 34]

is there any possible to have a mirror on svn?it so hard to make an update to the server if you made a lot of modifications.

[Nameless2you 97]

is there any possible to have a mirror on svn?it so hard to make an update to the server if you made a lot of modifications.

git actually makes it easier if you have modifications.

However it is also possible to do a svn checkout.

Check this out for more info: http://herc.ws/board/topic/152-obtaining-hercules/

[mofo 2]

git fetch upstream && git merge upstream/master

 

when i try this it says...

 

fatal: upstream does not appear to be a git repository

fatal: the remote end hung up unexpectedly

 

update: it works now, i just needed to configure the upstream.

Edited June 8, 2013 by mofo

[Jedzkie 58]

i just want to request to make a video how to pull request, because there are people (like me) still not get how to make a pull request, i just tried it but i get error when making push, "git did not exit cleanly, error (128)"

[jaBote 438]

Try to scroll up a bit, there's some explanation text up there. What does it say?

[Jedzkie 58]

Try to scroll up a bit, there's some explanation text up there. What does it say?

 

it say's "git did not exit cleanly, error code (128)"

[jaBote 438]

If you're using TortoiseGit, you'll usually get some more text if you scroll a bit up the error message, so that I know a bit more of info about that.

[Dastgir 1246]

Well, I use bash and till yesterday it was working fine, but now,

I can push my local changes of old branches but when I create new branch, then push it to repo, it just ask user and pass, thrn it stuck there, waited 1 hour, then also no change. Git processes seems to be running in background(in task manager it shows git applications), reinstalled git too. Set buffer size very high too, even tried to use ssh link, still no luck.

 

Any help?

[Brynner 34]

can you update this guide?

[jaBote 438]

OMG I didn't realise the pics were gone. I'm mostly out of here because of time and college issues, but will try to give it some time.

 

Any suggestion or just updating the images and text, if applicable?

[Brynner 34]

just the image only

[Angelmelody 221]

dunno why all the images become golden frog photos 

 

[evilpuncker 503]

because imageshack sux

[jaBote 438]

Imageshack was the only serious alternative to an image service I dislike (for personal reasons) such as imgur. Guess I'll have to swallow it. Not sure, but hope I still have the guide pics on my PC as I do with the other guides I wrote in Spanish...

[Dastgir 1246]

Imageshack was the only serious alternative to an image service I dislike (for personal reasons) such as imgur. Guess I'll have to swallow it. Not sure, but hope I still have the guide pics on my PC as I do with the other guides I wrote in Spanish...

Search , else I will screenshot a set of images for you xD

[zackdreaver 90]

Hail golden froggy

 

i prefer http://postimage.org/

[Brynner 34]

must better if you use postimage.org just like zackdreaver. all of my upload pics is came from postimage.

[AnutaBak 0]

How much memory do you have free in Activity Monitor with like Mail, Safari, iTunes, and iPhoto open?

656 meg. That is with 1 gig installed of course.