OpenXPKI Git Collaboration Howto

OpenXPKI uses Subversion as primary and authoritative source code control system. Keeping this repository in a clean state should be the primary goal of all developers.

However, this central approach reduces the possible interaction between developers: if one of them is working on some highly experimental code, it is frequently not desirable to check in this code into the repository. It would "pollute" the clean state and possibly break things that used to work. In this state the developer can only work alone on his personal source, nobody can help him properly. Even if interaction is not desired, Git can be used to easily create topic branches which makes life easier for a developer working on a number of different topics at the same time.

The main idea now is to continue using Subversion for the official checkins, i. e. development stages that are consistent within themselves (at least the automatic tests still run properly).

The dirty work gets offloaded to a second source code control system that works separately from Subversion and that allows ad-hoc collaboration: Git.

Collaboration models

One way around this problem is to use Git as a localized version control system in addition to Subversion. This document should help developers setting up their local Subversion OpenXPKI repositories for collaboration use with Git.

The OpenXPKI project supports three possible "development modes" for contributors:

Subversion only
Good old way of contributing code to OpenXPKI. You are not doing anything wrong this way. If you are happy, why are you reading this document at all...?
Subversion plus Git
Ideal for single developers or small teams collaborating on experimental features, yielding maximum efficience without "polluting" the official repository. This is appropriate if you are a registered OpenXPKI developer yourself.
Git only
Suitable for non-permanent developers or contributors. The easiest way if you plan to collaborate with another developer who has already created and published an own Git repository of OpenXPKI.

Common prerequisites

These steps should be performed if you wish to use Git with OpenXPKI regardless of collaboration model.

Set up proper author name and email address:

$ export GIT_AUTHOR_EMAIL="johndoe@example.com"
$ export GIT_AUTHOR_NAME="John Doe"

You can also set these values within the Git repository (in which case they only apply to this single repository) by adding the following to .git/config

[user]
        email = johndoe@example.com
        name = "John Doe"

Subversion plus Git

Initial setup

To checkout a subversion tree that is usable using git, you can use git-svn clone:

$ mkdir openxpki.git
$ cd openxpki.git
$ git-svn clone https://johndoe@openxpki.svn.sourceforge.net/svnroot/openxpki 
This will take quite a while as it will import the complete revision history from the subversion repository. Alternatively, you can clone a publicly available git repository, for example the one at repo.or.cz:
$ mkdir openxpki.git
$ cd openxpki.git
$ git clone git://repo.or.cz/openxpki.git

Daily usage

git-svn rebase fetches changes from the subversion repository and rebases your changes onto the latest subversion HEAD. If you want to push your git tree somewhere, you will want to do this only on the master tree (which will be your "clean SVN tree") and use git merge master in your topic branches.

git checkout -b mytopic master creates a new topic branch off of the master branch for you and changes into it. You can now work there, use git commit as often as you like until you're happy with your work. You can commit all your changes as single commits back to subversion using git-svn dcommit. If you're committing a lot locally (which is a good thing), you might want to create patches using git-format-patch master for everything you committed since branching off of the master branch, apply them manually to a temporary branch and combine things that belong together into one Git commit and run git-svn dcommit from that temporary branch.

For visualizing your commits and changes, using a graphical tool such as QGit or tig (if you like the console better) is recommended.

Collaboration

Add remote Git repositories for all people you want to collaborate with, for example:

$ git-remote add alech git://repo.or.cz/openxpki/alech.git

You are now ready to fetch or pull changes from the remote repositories, e.g. from the "alech" remote we created above:

$ git fetch alech

The changes "alech" published will now show up as tracking branches as "alech/master", "alech/sometopicbranch", etc. You can branch away from them, merge them into your local branches, etc.

In order to allow others to get your own changes you have to publish your Git repository. You will have to set up a publicly available Git repository to make this possible. Only you will need write access anybody else needs read-only access. We will assume that you will publish via ssh and that others get access via HTTP.

On the publicly available system create the remote repository directory and create the Git infrastructure:

remote$ cd ...
remote$ mkdir openxpki.git
remote$ cd openxpki.git
remote$ git-init-db

Configure your system to provide read-only access to ...openxpki.git for the public via HTTP.

Now add your own remote repository to your local git remotes by adding the following to your .git/config file:

[remote "mypublic"]
    url = ssh://johndoe@somehost.example.com/path/to/openxpki.git/

And finally push your local directory to the public repository:

$ git push mypublic

You can also push all your branches by saying git push --all mypublic

If you don't have a place where you can push your changes, have a look at repo.or.cz. There, you can set up your repository easily and for free, and you can even mark it as an OpenXPKI "fork", so it will be easier for people to find.

Git only

For Git-only-mode you can skip the Subversion checkout. Instead choose a Git repository to clone from and run:

$ git clone http://somehost.example.com/....git/openxpki.git

This automatically sets up Git to pull from this repository to the "origin" branch (check the .git/remotes/origin file for this). Setting up public repository replicas basically works the same as outlined in the above section.

Further reading

The following documentation might prove useful: