Developer Area/Language Packs/Translating and Git
From Mahara Wiki
< Developer Area | Language Packs
You've made a translation of Mahara, and you want to contribute on an ongoing basis by becoming the translation maintainer. Great! But Mahara uses this system called "git" for revision control, and you have never used it before. This document aims to give you a basic introduction to git, and how translators use it on the Mahara project to maintain their language packs.
If, after reading this, it seems too complicated, that's OK! We appreciate that translators are not necessarily technical people, and you shouldn't have to learn some fancy system in order to contribute. We're quite happy with you sending us zipfiles of your changes from time to time. Please get in touch through the Mahara Translation Group Forums.
Introduction to git
Git is a version control system. It allows us to keep track of changes made to files over time. As we change a file, we "check in" a copy of it to a git repository, which stores a copy of it for us. Then we can make changes to the file, and perhaps check in those changes too, or maybe revert back to the version we checked in. Think of "checking in" a file as if you were saving a computer game. If you mess up, you can reload the game from your last save point, and with git if you mess up you can just get your old file back - from any of its previous save points.
Note that there is git, the software, and the git repository. They are two different, but related things. If we have a directory of files that we wish to track changes for, we create a git repository in which to track those changes. To create that repository, and to check versions of files into it, or to get files back out of it again, we use the git software. The git software manages git repositories, which track changes to files. Got it?
How to install Git
The first thing we need to do to start working with Git is to download the software. Most of the linux distributions have package managers to install new software without having to know the linux command. Otherwise, you can install Git from the console. The command depends on the linux distribution. In Ubuntu, for instance, it would be:
apt-get -y install git-core
Within your user directory, you will see that a folder called "git" has been created and within it, a hiden folder alse called ".git".
Start working with GIT
In Mahara, we use git to track the source code, which also includes the language packages. Imagine, for instance, that you have started to translate Mahara into your language, or you are working on the code, but then suddenly, your work priorities change and you cannot commit to do any more. So, you have to record and check all the changes that you have made, and you have to tell other Mahara developers about these changes and why you made them, so that they can continue your work just where you left it. This is one of the useful things that we can do with Git . Each time we make a check in, Git records a few things about it. It records who made the change, when it was made, what files were changed (you can check in more than one file at once), and a short message about the purpose of the changes. This is called a commit. So, no matter how many developers are working with the Mahara core code, there is always an updated copy with all the changes checked and committed, and this copy is kept in a git repository.
'W'here is the git repository?...
The answer is, each developer has their own git repository, and there is a "master" repository on git.mahara.org. Commits can move from repository to repository. In our case, each developer started their own repository by copying the one on git.mahara.org. They can then make changes (and check in those changes) in their own local repository. Then they can send all those changes back to git.mahara.org, for other people to copy.
So, the first thing you need to now is how to connect to git.mahara.org, where the master repository is kept. You need to create and account first , and you need to create a ssh key from your computer that you will need to pass to git.mahara.org. To generate this key, from the linux terminal type:
ssh-keygen
By default, this password will be stored in the .ssh/id_rsa.pub file. Say yes to confirm. Thi is the password that you need to pass to gitourious.
The next step is to get a copy of original code from the master repository. This is called "to clone" the git repository because we are going to create an exact copy of the code in the master repository in our local repository.
This can be done with the instruction:
git clone git://git.mahara.org/mahara/mahara.git
for the core code,
or for the language packages:
git clone git://git.mahara.org.org/lang-old/your language package.git
Go now to the folder that contains your local repository (the code that you have cloned from gitourious.org). You will see a hiden folder called .git. There is one file there that you need to knew, the config file. This is how the file looks like:
[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
[remote "origin"]
url [email protected]:lang-old/es.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
remote = origin
merge = refs/heads/master
[branch "1.2_STABLE"]
remote = origin
merge = refs/heads/1.2_STABLE
notice that the url for the [remote "origin"] is
url [email protected]:lang-old/es.git
as this is the config file for my local repository of the Spanish language package.
For the local repository of the Mahara' s development code, it would be:
url = [email protected]:mahara/mahara.git
A Basic Example
So, adding it all up so far, we have:
- git allows us to track changes to files
- these changes are stored in a git repository
- we can send these changes to the master repository, and receive changes from this repository too.
Here is a simple example of how two developers (let's call them Nigel and Penny) might work on Mahara, using git.
Nigel wants to work on Mahara, so the first thing he does is make a copy of the git repository from git.mahara.org. This gives him a directory that has all the Mahara files in it, plus it sets up a local git repository for him to track his changes.
He then makes some changes to one or two files, in order to fix a bug. Once he's happy he's fixed it, he makes a commit. Commits can have messages attached to them, so he says that this commit fixes the bug.
Now his local repository has one commit that the one on git.mahara.org doesn't have. He could continue working, making more commits, but decides to send his commit back to git.mahara.org.
Meanwhile, Penny is working on the code in her git repository. She decides to check git.mahara.org to see if there are any new commits. It turns out there is one - the change Nigel just made. So she fetches that commit, and applies it to her repository. Now she has the bugfix too.
A basic guide to GIT
There are many user guides, but if you want to learn the fundamentals of GIT and its basic commands in a relatively short period of time, Git for the lazy is probably the best one and it only takes around 10 minutes to learn the basic commands.
TODO
Our git server
Our branch layout and how it applies to your repository
Workflow of a translator