Learning git/github with WoWPro Addon - Part 2

Silvann's picture

This is the Part 2 of the guide on how to use git / github, covering Forking github projects and managing local and remote repositories.

Here's the link to part 1.

Table of Contents

  1. Tutorial: Forking & Remote repository
  2. Tutorial: Setting up keys
  3. Tutorial: Creating a local repository
  4. 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! Eye

Comments

Ludovicus's picture

I Wish ...

I wish the documentation on GitHub was as clear.

Of course, it is still PC centric and us poor Apple Snobs.

Perhaps, I will pull together the Mac variations ...

Silvann's picture

I actually prefer the git

I actually prefer the git command line, which would make the guide more portable, but it seems most people are more used to PC/gUI/Windows.

Ludovicus's picture

Command LInes for Manly People

Yeah, I never even thought of using the Mac GUI interfaces into git.   I use windows machines at work, keep a Mac on my desk at home and have a Linux server for my home network.   The git command line is nicely consistent between all three.

At my advanced age, who wants to learn more applications than is necessary!

 

WoWPro, git and Xcode

Warning....Mac information follows.  Those who could care less about it please feel free to ignore.

Since I converted to maintaining my own addons with git instead of svn I decided to actually do the text editing in Xcode.  It made the next step much easier as well...integrating the helper code into the projects as well.  So all my code that I write to get localized versions of things, ensure "referential integrity", etc. all stays with the addon code in one project.  Then I can deploy a new addon by installing and only the latest and greatest addon files get installed, not the support code.

I mention this because lately I have been tempted to actually do some work on WoWPro.  I think my development of Wholly has gotten to a point of stasis as I have no other features to add at the moment.  And Grail is all that needs to be worked on.  But with Wholly I have seen some overlap with WoWPro and I was wondering what can happen with WoWPro and making it into a database.  Therefore, I was thinking of making an Xcode project from the git repository.  I have no idea whether I want to tackle transforming what WoWPro currently does to something a little more modern and unified as I understand there are already efforts to that end underway.  Just musings.

Enjoy.