Learning git/github with WoWPro Addon - Part 1

Learning git/github with WoWPro Addon - Part 1

This is the Part 1 of the guide on how to use git / github, covering Introduction and Installations.

Table of Contents

  1. Introduction
  2. What’s git?
  3. What’s github?
  4. Tutorial: Getting started



1. Introduction


WoWPro addons are developed using a control version system called git and hosted in github, a git public hosting site (I’ll explain what that means later on). Although you are definitely not required to learn git in order to contribute with WoWPro addons, it certainly wouldn’t hurt. Eye

  • Who this guide is for exactly?

It is mainly designed to be useful to WoWPro addon developers, allowing them an easier and more resourceful access to the project. For people out there with some programming skills, who want to contribute with the development of the addon, then this guide is definitely for you! Along with the tutorials themselves, I'll also show some "etiquette" suggestions when using git / github.

For guide writers/coders/editors, this guide can certainly be also useful. However, just be aware that we are trying to centralize guide edits, posts and bugs on their respective community pages here on WoWPro.com. So, we ask you to not push your changes directly into the original github's project. But even with this restriction, using git can help tremendously in your task! I'll explain all that in the next part of the guide, as well as some "etiquette" suggestions.

For people who are reading this guide right now and have no idea what this is all about (like general WoWPro addon users), but are curious and willing to learn new things, then I invite you to also read the guide. But I won’t mind if you go somewhere else. Smiling

Also, this guide assumes Windows users, but if you have another operating system, you should be able to follow it just fine, as the git user interfaces should be similar across OSs.

  • What this guide is not?

There is a plethora of guides, tutorials, articles on how git will save the world, articles on how git sucks, etc on the Internet and it is not my intention to compete with them (in fact, I’ll provide several references at a later time). Partly because it wouldn’t be useful to the community here and partly because I’m not an expert on this subject! So, this guide is really just an overview of git and github, with some tutorials focused on WoWPro addon.



2. What’s git?


Let’s say you have a project composed of text files, that you continuously perform changes. Since the changes can be somewhat sensitive, you then decide to keep track of different versions of the same files, over time. The classical way is opening up the relevant, original file in a text editor, make the changes you want, and then use the “Save as...” option. Then, the name of the new file can be the original’s, plus some other identification, like a version number or the date it was created/modified.

But as the number of versions increases, it gets difficult to know what each of them actually means with just different name files. So, you could also improve this pedantic version control by writing, at the beginning of the text file, a change log, enumerating all the changes you performed in that particular version.

It works, but as you can see (for a number of reasons), this cumbersome system does not scale well with the number of files/lines, number of versions, etc. So people developed other, smart control version systems, of which git is one of them. These can perform easily all the processes described above and more! You’ll see some of the functionalities later on.

Before we get to the tutorials, there’s something else I should mention: what happens if you have more than one person working on the same project? This leads us to github...



3. What’s github?


You can do all the control version processes described above with git, in your local computer. You don’t really need to be like me, who does not remember even what he had for dinner last night, to appreciate easy access to changes / versions / comparisons in a personal project you’ve been working on, say, for months.

But a control version system really shines when more than one person is working on the same project, especially nowadays with all the open source projects and global collaboration. For that, a git project can be hosted in a server, which can then be accessed (and potentially modified), by people around the world through the internet.

Github is git hosting site, which provides interesting functionalities to project management and collaboration. You’ll learn some of them in the next tutorials.


Nomenclature:
Repository (repo, for short): a git project, its files and information stored by git, 
such as the different project versions. A repository can also refer to a 
full copy of a git project (more on that later).  If it’s located in your local computer, 
then it’s called “local repository”. If it’s shared, in a server, it’s called remote 
repository. Usually, you need a local repo in order to work with a remote one.


Now let's get on the hands-on...



4. Tutorial: Getting started


Let’s start by downloading and installing git. There are several tools and interfaces that you can use to do git control version, from the blander, but more robust command lines to graphical interfaces. For this guide, we’ll use a git interface for Windows, called Git Extensions. For a complete list of interfaces, including the original one for unix/linux, check the following reference link: Git Interfaces list.

You can download the latest version of Git Extensions from here:

http://code.google.com/p/gitextensions/

Or more directly, for the version as of this writing, here:

Direct Download Link

Run the downloaded file to begin the installation:

Unless you have absolutely sure you have the required softwares, check to install both of them and continue in Next:

For the next step, leave the installed features as they are, just click Next. But here, let's use Putty:

Then, just continue with the installation. At some point, it will ask you to install Git (which is actually the core’s program) and kdiff3, which you shouldn’t worry about it. For both, just use the default options as they are and keep clicking “Next” or “Continue”.

If the installation is successful, you should see a new icon on your Windows desktop (and/or somewhere in the Windows Programs menus), that looks like... hmm... a Tauren?. Open the program Git Extensions, click “Ok” if a checklist settings window is shown, and you should finally see something like this:

For this guide, as you can see, we’ll use the graphical interface, but don’t be afraid to use the git command line if you want to. Git commands are few and easy to remember (yes, even to me), since they are all English words. If you want to try that later, you should see a program called git bash, which opens the git command line.

Ok, now let Git Extensions rest for now and let’s deal with github...

Go on github.com and click on the big, blue button. Don’t be scared about the plans, prices... for public projects such as the WoWPro addon, github is completely free, easy and quick to sign up and use.

Now, choose the Create a Free Account option. Unless you already have a github account, just choose an username, e-mail, password and you’re good to go. Your github home looks a little empty right now... but we'll fix that in the Part 2 of the guide!

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.

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