Version Control for Koha using Git

So you want to contribute code to Koha, that's great! First off, welcome to the community, we're glad to have you.

First I want to say a word about version control. Why use version control at all? It may be tempting if you download koha and install it for your library to just edit the files to customize it for your local needs outside the context of a version control system.

But spending a few minutes learning how to use a version control system will open up a whole new set of ways you can interact with the koha community, and will make it easy to update your production system, easy to test revisions, and easy to contribute those back to the main project. So if you're going to write or customize Koha code, take a few minutes to familiarize yourself with the primary tool us Koha developers use for version control.

This should be considered a working document, as we all get used to using git, and we get more developers on board, our workflow is likely to change.

Our goal is to make it as easy as possible to integrate patches from the community, and to make it as easy as possible for all developers to work with the project repositories as well as the features they are developing for their libraries/customers

motto “Every time a patch falls on the floor, a kitten dies”

Release Manager: responsible for feature freezes, scheduling a release

QA Manager: responsible for defining coding practices and ensuring that code conforms to coding practices

Developers: write code, document it, push it out

Public: do you want to be updated with the last changes without writting code

coming soon

Git: http://git.or.cz/

In general, a newer git is best, the project's public repo runs 1.5.2.1

The project's public repository, including commit logs, diff viewing, and searching, can be browsed on the Web at http://git.koha.org/

Set your name & mail address with :

git config --global user.name "your NAME"
git config --global user.email "your@mail.com"

You may also have to set up an SMTP server :

git config --global sendemail.smtpserver "smtp.address.com"
git config --global sendemail.smtpuser "login@email.addres.com"
git config --global sendemail.smtppass "password"
git config --global sendemail.smtpssl "true"

Specify that patches are formated in UTF8 (required for patches containing French accents for example):

git config --global format.headers "Content-Type: text/plain; charset=\"utf-8\""

Clone the public repository:

git clone git://git.koha.org/pub/scm/koha.git kohaclone

You're gonna get a bunch of stuff that looks like:

 $ git clone git://git.koha.org/pub/scm/koha.git kohaclone
 
 remote: Generating pack...
 remote: Done counting 16310 objects.
 remote: Deltifying 16310 objects.
 remote:  100% (16310/16310) done
 Indexing 16310 objects.
 remote: Total 16310, written 16310 (delta 10657), reused 12014 (delta 7834)
 100% (16310/16310) done
 Resolving 10657 deltas.
 100% (10657/10657) done
 Checking files out...
 100% (3429/3429) done

To clone the repo using the Git protocol (git:), you need to be able to connect to port 9418 on git.koha.org. If for some reason you have a restrictive firewall that cannot be changed, and using SSH port forwarding is not an option, it is possible to clone the repo using HTTP:

  git clone http://git.koha.org/pub/scm/koha.git kohaclone

Other git operations such as git fetch and git rebase will work normally after you clone using HTTP.

Note that because this requires a cronjob (git-update-server-info) that is set to run every 10 minutes, cloning or fetching over HTTP can result in a repo that's slightly out of date with respect to the public repo. As a general note, unless you absolutely have to use HTTP because of restrictive firewall rules, using the Git protocol is more efficient, both for you and the server that hosts the repository.

You will want to create a branch to work on.

If you want to track the current development version, which is on the master branch's HEAD, do this:

$ cd kohaclone
$ git checkout -b mywork origin

If you want to track the maintenance branch of an earlier version of Koha (e.g., 3.0.x), you can do the following:

$ cd kohaclone
$ git branch -r
  origin/3.0.x
  origin/HEAD
  origin/master

The origin/3.0.x branch is the name of the maintenance branch for Koha 3.0, including future bugfix releases such as 3.0.1. To make a local (to your repository) branch to track this (remote, from git.koha.org) branch, you can do the following:

$ git branch --track 3.0.x origin/3.0.x
$ git checkout 3.0.x

If, after doing this, you want to create a branch on top of the 3.0.x branch in order to do some work, you can do this:

$ git checkout -b my-3.0-work

OK, now you've got your own clone, you're ready to get to work. Lets say you're a template designer who works for the Nelsonville Public Library and you're working on some improvements to the templates in Koha Version 3.0.

So at this point, you're ready to do some work. You'll be able to work within this 'clone' you've created, with version control, so you'll have a complete history of your work, without affecting the rest of the project; and you'll also have a simple way to notify others of the work you've done so they can test it out.

If you've used CVS before, this next bit is gonna be pretty standard. After you've made some changes to a file, simply go:

$ git commit file

You can also just commit a bunch of files with:

$ git commit -a

You can see how your recent commit fits into the context of all other commits in this branch/clone with the log command:

$ git log

Sometimes you'll be working on something on a branch that needs to be updated to the latest 'origin'. Running the following commands will grab all the changes since you last pulled and merge them with your current changes:

$ git fetch
$ git rebase origin

If you are working on a branch derived from the 3.0.x branch, you should rebase against origin/3.0.x:

git rebase origin/3.0.x

So now we're happy with our work, and we're ready to show it to the world.

The way we do this is the same way as the way the developers for the linux kernel work. We use the tools in git to format a patch and send it to the QA manager. Once that patch has been approved, it is pushed on to the RM Manager who has final say on where the patch will be applied.

To create a patch and send it to the QA Manager, issue:

$ git format-patch origin

It will generate one or more patch files. Now send it off:

$ git send-email 0001-filename

and choose koha-patches@lists.koha.org for the TO: address. (Note: koha-patches@lists.koha.org is a mailing list and can be subscribed to at http://lists.koha.org/mailman/listinfo/koha-patches. Discussion of patches occasionally occurs on this list, so it is recommended that active Koha developers subscribe to it).

Alternatively, if you want to see what has to be commited, just do

$ git diff

or

$ git diff --name-only

If you are doing a patch of a bunch of file moves or deletes:

git-format-patch -M -B origin

if you just want the file names

Then, use git-format-patch; for example:

$ git format-patch origin

will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD.

You can then import these into your mail client and send them by hand, or use your command-line mailx command like thus:

$ mailx koha-patches@lists.koha.org < 0001-mypatch

However, if you have a lot to send at once, you may prefer to use the git-send-email script to automate the process.

The QA will then apply the patch (if its a bug fix and it meets the coding guidelines) or will escalate the patch to the release manager to apply.

You might want to delete your branch and/or create another branch you can do that by

git branch -D branchname

To delete

git branch branchname

To create a new one

Ok, the release manager has received some patches and wants to apply them.

Git also provides a tool called git-am (am stands for “apply mailbox”), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a single mailbox file, say “patches.mbox”, then run

$ git am -3 -i -s -u patches.mbox

Git will apply each patch in order; if any conflicts are found, it will stop, and you can fix the conflicts as described in “Resolving a merge”. (The ”-3” option tells git to perform a merge; if you would prefer it just to abort and leave your tree and index untouched, you may omit that option.)

Once the index is updated with the results of the conflict resolution, instead of creating a new commit, just run

$ git am --resolved

and git will create the commit for you and continue applying the remaining patches from the mailbox.

The final result will be a series of commits, one for each patch in the original mailbox, with authorship and commit log message each taken from the message containing each patch.

Now they want to update the public repository so the rest of the world can get the new code.

The simplest way to do this is using git-push and ssh; to update the remote branch named “master” with the latest state of your branch named “master”, run

$ git push ssh://yourserver.com/~you/proj.git master:master

or just

$ git push ssh://yourserver.com/~you/proj.git master

As with git-fetch, git-push will complain if this does not result in a fast forward. Normally this is a sign of something wrong. However, if you are sure you know what you're doing, you may force git-push to perform the update anyway by proceeding the branch name by a plus sign:

$ git push ssh://yourserver.com/~you/proj.git +master

Note that the target of a “push” is normally a bare repository. You can also push to a repository that has a checked-out working tree, but the working tree will not be updated by the push. This may lead to unexpected results if the branch you push to is the currently checked-out branch!

As with git-fetch, you may also set up configuration options to save typing; so, for example, after

$ cat >>.git/config <<EOF
[remote "public-repo"]
        url = ssh://yourserver.com/~you/proj.git
EOF

you should be able to perform the above push with just

$ git push public-repo master

See the explanations of the remote.<name>.url, branch.<name>.remote, and remote.<name>.push options in git-config for details.

The QA manager will receive patches and will want to either apply them and then push them upstream to the RM's repo or escalate the patch for the RM to view.

The QA manager needs to check if the patch is a bugfix or a new feature. If it is a bugfix they then need to check that it confirms to the coding guidelines. If it does they can then apply the patch (the same way as the RM does). Then they do a git-push to push this back to the RM's repository. If they are new features, the QA Manager will forward them to the Release Manager to look at.

For example

1. Check mail
2. Look at new patch email, its a bug fix, looks good, save to a file to_apply

3.  git-am to_apply 

4.  git push 

5. Let the RM know.

OR

1. Check mail
2. Look at new patch email, ooh a neat new feature, forward to RM Manager

Clone the public repository

git clone git:git.koha.org/home/pub/scm/koha.git whateveryouwanttocallyourrepo You're gonna get a bunch of stuff that looks like: git clone git:git.koha.org/home/pub/scm/koha.git kohaclone

 remote: Generating pack...
 remote: Done counting 16310 objects.
 remote: Deltifying 16310 objects.
 remote:  100% (16310/16310) done
 Indexing 16310 objects.
 remote: Total 16310, written 16310 (delta 10657), reused 12014 (delta 7834)
 100% (16310/16310) done
 Resolving 10657 deltas.
 100% (10657/10657) done
 Checking files out...
 100% (3429/3429) done

To update the files in your machine:

cd /your path/kohaclone

git pull

You're gonna get a bunch of stuff that looks like:

git pull

 Updating a4d6314..3d41470
 Fast forward
 C4/Biblio.pm                                       |  209 +-
 C4/Branch.pm                                       |   16 +-
 C4/Breeding.pm                                     |    7 +-
 C4/Circulation.pm                                  |   48 +-
 C4/Context.pm                                      |    3 +-
 C4/Items.pm                                        |    6 +-
 C4/Koha.pm                                         |  550 +-
 C4/Languages.pm                                    |   38 +-
 C4/Output.pm                                       |   19 +-
 C4/Reports.pm                                      |   51 +-
 C4/SIP/ILS/Transaction/Checkout.pm                 |    5 +-
 C4/SIP/ILS/Transaction/Renew.pm                    |    3 +-
 INSTALL.debian                                     |    7 +-
 Makefile.PL                                        |    3 +
 admin/cities.pl                                    |   12 +-
 admin/letter.pl                                    |   15 +-
 admin/printers.pl                                  |   13 +-
 admin/roadtype.pl                                  |   12 +-
 .../intranet-tmpl/prog/en/includes/help-bottom.inc |   11 +-
 .../intranet-tmpl/prog/en/includes/help-top.inc    |    4 +-
 .../prog/en/includes/reports-menu.inc              |    6 +
 .../prog/en/includes/sysprefs-menu.inc             |    2 +-
 t/Accounts.t                                       |    3 +

After you have successfully pulled a new 'Koha' repo and you want to rewind your repo back to the Release-Candicate-1 tag (as it's currently at HEAD) for a nice safe install, try this…

  git fetch --tags
  git reset --hard v3.00.00-stableRC1

If you want to mail the diffs, put the following in the post-receive file:

echo “Summary of changes:”

  git diff-tree --stat --summary --find-copies-harder $oldrev..$newrev
  git diff $oldrev $newrev

French tutorial / doc :

I (Paul) have found that http://wiki.archlinux.fr/howto:production:git is very clear and usefull

NOTE if you get this error:

  Environment problem:
  Your name cannot be determined from your system services (gecos).
  You would need to set GIT_AUTHOR_NAME and GIT_COMMITTER_NAME 
  environment variables; otherwise you won't be able to perform
  certain operations because of "empty ident" errors.
  Alternatively, you can use user.name configuration variable.
  
  fatal: empty ident  <jmf@arwen.metavore.com> not allowed

You're probably using a slightly older version of git that needs you to export some variables:

$ export GIT_AUTHOR_NAME=“whatever”

$ export GIT_COMMITER_NAME=“whatever”