Learning git/github with WoWPro Addon - Part 2
This is the Part 2 of the guide on how to use git / github, covering Forking github projects and managing local and remote repositories.
Table of Contents
- Tutorial: Forking & Remote repository
- Tutorial: Setting up keys
- Tutorial: Creating a local repository
- Important notice for WoWPro project
1. Tutorial: Forking & Remote repository
So, by now, you should have your very own github account.
Let's add a project to it, by "forking" WoWPro’s addon, from Jiyambi’s original repository.
Nomenclature: Fork: make a full copy of a github project in order to start independent development on it.
For that, while logged into Github, go to Jiyambi’s repo, here: http://github.com/Jiyambi/WoW-Pro-Guides
And click the "Fork" button. You can also click Watch, to receive notifications and news, by e-mail and on your github homepage, related to the project.
Ok, now you have a forked version of WoWPro's addon. Don’t worry about all the news things that came up on that page, we’ll be dealing with some of them as the guide progress.
As you can see, your forked project is called username/WoW-Pro-Guides, which will be your personal remote repository of WoWPro.
But now, to actually modify it, as I hinted before, we need to have a local repository of that remote. For that, we go back to gitExtensions. (From now on, try to keep both gitExtensions and the github site opened and/or minimed for quick access).
2. Tutorial: Setting up keys?
Before we go on with the tutorial, let me explain a bit the next steps. The communication between your local and remote repo(s) is done via the SSH protocol, by using a pair of keys that can recognize each other. One of the keys, called private, will be stored on your local computer (and attached to you local repo) and the other key, public, will be given to github (the remote).
But how do we create a pair of keys in the first place? Fortunately, GitExtensions has a tool to generate pretty unique keys. Click on Remotes->PuTTY->Generate or import key.
Click on Generate and you get a short and easy mini-game: just keep moving your mouse cursor around until you complete the green bar and the keys get generated.
For the private key, you'll just need to save it in your computer by clicking 'save private key button'. We'll use it in a minute, so save it with a file name and in a location you'll remember (unless you want to it to play the mouse cursor mini-game again!)
You should also see a field, highligthed above, with random characters on the top of that window: that's the public key. It starts with 'ssh-rsa' and ends with '==somename'. We are going to copy that public key (exactly as it is) and paste it in the following place, on github: Account Settings -> SSH Public Keys -> Add Another Public Key:
Before minimizing/moving on, let's copy the repo remote address. Go to your forked project home, and copy the address highlighted below ( should be like :username\WoW-Pro-Guides.git ).
3. Tutorial: Creating a local repository
Now let's finally download the repo. Go back to GitExtensions, click on 'Clone repository'. Paste the just copied address into the field: 'repository to clone', choose a place for it in 'destination'. In the field 'branch', just pick 'master'. It should look like the following:
Now click on Load SSH Key to load the generated private key we saved earlier. Then, click on Clone. If all is well, you should see the download of the repo and, at the end, the notice that the cloning was successful. If not, go back to the 'generate keys' section. If you're still getting errors, post a comment on this thread.
Important notices for WoWPro project
Before moving on with the guide (in part 3), which will deal with the actual editing of file codes, I'd like to draw attention to two things regarding how WoWPro addon project is organized:
- If you follow my guide here, you'll notice that I taught you how to create your own version (forked) of WoWPro addon. For the part 3 of the guide, if you keep following it, any changes you make to the file codes (locally and, then, remotely) will not automatically be incorporated into the "official" addon project itself. Instead, the changes made will lie on your forked version (username/WoW-Pro-Guides). After that, if you'd like your changes to be incorporated into the addon, I'll explain how to "open a ticket" to Ludovicus or Jiyambi so they can analyze the change and make the merge.
- To make it easier for Ludovicus or Jiyambi to update the addon with the recent guide changes/correction, the guide files should be updated on their respective pages here on WoWPro. So, even though you could make the changes through git/github, you should do them by editing the pages on WoWPro, or your changes won't make through.
Part 3 should be up soon, where by soon (tm) I mean when it's ready!