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:
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
Step 2: Fork Hercules project in GitHub
Steps 3 to 6: Local computer work
Step 7: (Finally) submitting the pull request
Congratulations! You have successfully made your first pull request on Hercules! This is a reason to be proud of yourself, isnt it?
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.
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.
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.
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.
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.
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 
"
[*]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:
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.
"- 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 masterYou'll also be asked for your GitHub username and password, just like windows but in the command line interface.
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?
Last edited by a moderator:
