Before you can start developing you need the source code. The code is managed in a GIT repository.

For working with X2go Git you have to install some software on your development workstation. We will presume you develop under Debian:

$ aptitude install git devscripts

We currently use Debian based tools to maintain the projects' changelogs. This may change in the future (in order to become even more generic and Debian-independent), but for now, developers should add these lines to ~/.devscripts:

DEBCHANGE_RELEASE_HEURISTIC=changelog
DEBCHANGE_MULTIMAINT_MERGE=yes
DEBCHANGE_MAINTTRAILER=yes

and these lines to ~/.bashrc:

export DEBFULLNAME="<Firstname Lastname>"
export EMAIL="<my.mailaccount@mydomain.com>"
export DEBEMAIL=${EMAIL}

There are a few different approaches for working on X2go code (or Git-hosted code in general). This wiki page will address two of them: HEAD development and local branch development.

With the term HEAD one refers to the topmost recent code in a code repository. The Git branch that HEAD development gets committed to is the master branch of each X2go Git project.

If you are a core X2go developer and the code you are working on is something that is intended to become a core component of X2go then you are likely to directly work on HEAD.

Also bug fixes should be committed to the master branch directly.

However, if you work on a piece of code or a feature, that may or may not become a part of X2go or a piece of code that will break a couple of things when committed to the master branch then you should rather start a local branch to work on that.

If you want to branch of from HEAD, use this command:

$ git checkout -b <my-local-branch-name>

If you want to branch of from some old release/refspec then use these commands:

$ git checkout <blessed-refspec-or-tag>
$ git checkout -b <my-local-branch-name>

You then continue your work on the <my-local-branch-name> branch and commit your changes there.

You may also upload your local branch to the X2go Git site. Please discuss this first on the x2go-dev mailing list.

$ git push <my-local-branch-name>

To incorporate changes from your <my-local-branch-name> you may use e.g. the git-cherry-pick command or the git-checkout command.

Note: The only thing we do not accept on X2go Git are Git merges.

There are some recommendations that we give when coding X2go and committing in X2go Git:

• run git-pull before starting to work on new code snippets (to avoid nasty merge problems)
• code in little portions
• commit in little portions
• important commits always have a representative line in the project's changelog (currently: /debian/changelog, this may change)
• do not combine code of two different features/bugfixes/etc. in the same commit

Before you change something:

$ git pull

After you have performed some changes on an X2go Git project, please use the git-commit command to commit your changes to your local Git:

# commit everything
$ git commit -a

# commit specific files
$ git commit <file-1> <file-2> <file-etc>

You will be presented an editor to add a commit message. If you want to give the commit message on the command line use the -m option:

# commit specific files
$ git commit <file-1> <file-2> <file-etc> -m "Fix something in file 1, 2 and etc."

In case you have lost track of files that have changed since the last commit, you can use the git-status command:

$ git status

New files and folders can be added with git-add:

$ git add <file-3> <folder-2>
$ git commit <file-3> <folder-2> -m "This message should explain why you have added file 3 and folder 2..."

Currently we use Debian tools to maintain each project's changelog file. Debian tools are optimal for developing Debian packages. For an upstream project like X2go we have to find something that's more generic.

However, as this is in process and till it has settled, please continue as described below when maintaining the X2go projects' changelog files.

1. code your code
2. before you commit, run dch
3. explain what you have changed about the code
4. save your changes
5. run the debcommit command instead of git-commit, it accepts a similar set of options.

For more information on the used Debian tools refer to the dch and the debcommit man pages.

If you forget to run git-pull before modifying code files you will run into merge problems when committing your changes.

There is nothing bad about merge commits apart from the fact that the X2go Git system won't allow them being pushed to the server .

Thus, you probably want to avoid merge commits right from the beginning. However, from time to time it occurs that you crunch your Git log with a merge commit. This is how such a thing can happen:

• change a file
• commit it locally
• push it to X2go Git
• find that the push operation gets rejected
• then run git-pull instead
• and then uuups… realize: the git-pull fetched in some code for the same file, I have just been working on…) → you probably forgot to run a git-pull before starting to work on that particular file…

One possible solution for this is cherry-picking. Here is an example (presuming that your are working on the master branch):

# make a temporary backup copy of the master branch
$ git checkout -b master-bak-tmp

# go back to master branch
$ git checkout master

# and reset it to that refspec where local Git and server's Git were known to be still in sync
$ git reset --hard <last-refspec-known-to-be-identical-with-server>

# then take a look at the log of your old local master branch
$ git log master-bak-tmp

# now cherry-pick your local changes individually from the master-bak-tmp branch (where refspec-1 ... refspec-n are the commit hashes of each commit):
$ git cherry-pick <refspec-1>
$ git cherry-pick <refspec-2>
...
$ git cherry-pick <refspec-n>

# finally drop the tmp backup of old master
$ git branch -D master-bak-tmp

Whenever your local X2go Git project is in an acceptable state for the community, feel free to push the code to the X2go Git server:

$ git push

The update scripts of X2go Git will shout warnings at you while pushing. These warnings relate to

• whitespaces found at the end of lines
• tabs found in the file (for Python: no tabs, for Bash, Perl, C++, etc. tabs are wanted, so you can ignore these if not coding Python)
• no \newline at end of file

You may consider silencing those warnings before committing the next time…

The X2go version scheme is a four digit version number: <major>.<minor>.<micro>.<nano>

For releasing X2go components make sure that you have a GPG key for your commit mail address available and installed on your local system. The commit mail address can normally be found in ~/.gitconfig (see above).

If you decide for releasing an X2go component, please perform the following steps:

1. Change any string location in the project that reflects the version number: changelog, VERSION.<x2go-project> file, maybe there is a version number somewhere in the code (Python: init.py files)
2. Change the UNRELEASED tag in the /debian/changelog header to unstable, this can be done by using dch -r.
3. Commit and push the versioning updates
4. Tag (and GPG-sign) the pushed code with

   $ cd ~/MyCode/x2go-upstream/<x2go-project>.git
   $ git tag -s <a.b.c.d> -m "Upstream version <a.b.c.d>
   $ git push --tags

5. Use the x2go-updatebuildmain script from the X2go buildscripts to update the build-main branch of the project

   $ x2go-updatebuildmain HEAD

6. Run x2go-tarballrelease in the base folder of the X2go Git project to be released:

   $ x2go-tarballrelease <a.b.c.d> [<blessed-refspec-or-tag>]

   The tarball will then be moved to this location: ../_releases_/source/<project>/.

7. Sync the new tarball to code.x2go.org, a recommended tool for keeping a local _releases_ folder in sync with the releases folder on code.x2go.org is unison/unison-gtk.
8. Send an e-Mail to the Git Administrator to extra-inform him about a new component release.
9. Maybe even kick-off a Lauchpad package build for Ubuntu (if impatient or if you intend to change more on master's HEAD before the next package build).
10. Before you continue working on the code you should make sure that the newly released code has been built on Launchpad and also moved to the x2go-stable PPA.

For Git / code administation you have to be able to logon to the host code.x2go.org as user x2go-admin:

ssh -lx2go-admin -p32032 code.x2go.org

As x2go-admin you can:

• create new X2go Git projects
• edit Git configs
• edit Git descriptions
• edit Git ACLs (currently not in use)
• upload released tarballs and binaries (Win32, MacOS X)
• build packages (not recommended on code.x2go.org, as no KVM support is available on that machine)
• upload Debian packages to http://packages.x2go.org/debian

The X2go project uses a hand full of build scripts that are also hosted in X2go Git:

$ mkdir -p ~/MyCode/x2go-upstream
$ cd ~/MyCode/x2go-upstream
$ git clone ssh://x2go@code.x2go.org:32032/srv/git/code.x2go.org/buildscripts.git

The buildscripts.git Git project contains a /bin folder in which you find a series of helper scripts. Symlink all of these script files to your personal ~/bin directory:

$ mkdir -p ~/bin
$ cd ~/bin
$ ln -s ~/MyCode/x2go-upstream/buildscripts/bin/* .

And make sure it is included in your user's PATH variable:

echo $PATH

If you cannot find a hint that ~/bin is included in the PATH variable, add it to it:

echo 'PATH=~/bin:$PATH' >> ~/.bashrc

After extending the PATH variable log off an on to make sure it takes effect (or use your own style of letting it take effect).

If you want to create a new X2go Git project on code.x2go.org please discuss this first on the x2go-dev mailing list.

Then create a local Git project:

$ mkdir -p ~/MyCode/x2go-upstream/x2gonewthing
$ cd ~/MyCode/x2go-upstream/x2gonewthing
$ git init

Then add your first files to the new x2gonewthing project. Commit these files as the first commit. Maybe commit more…

Then run the following command sequence:

$ cd ~/MyCode/x2go-upstream/
$ x2go-gitcreate x2gonewthing
# if the Git creation succeeds (check via http://code.x2go.org/gitweb), only then...
$ rm x2gonewthing -Rfv
$ git clone ssh://x2go@code.x2go.org:32032/srv/git/code.x2go.org/x2gonewthing.git

Now you can start working on your new X2go project as on any of the other already existing X2go Git projects.

As x2go-admin on code.x2go.org:

$ cd /srv/git/code.x2go.org/<x2go-project>.git
$ vim config

As x2go-admin on code.x2go.org:

$ cd /srv/git/code.x2go.org/<x2go-project>.git
$ vim description

Unused feature, may come later…

The equivalent of http://code.x2go.org/releases can be accessed on code.x2go.org like this:

$ cd /srv/sites/x2go.org/code/releases

On code.x2go.org there is a qemubuilder build environment installed. However, as the underlying system is already a VM, and thus, does not render KVM support (qemu software emulation only ), building packages with qemubuilder on code.x2go.org is not at all recommended.

Currently, packages for Debian are built on a non-public machine at DAS-NETZWERKTEAM in Northern Germany and then get uploaded to code.x2go.org aka packages.x2go.org.

As x2go-admin you have upload rights for the X2go Debian repository. Use Debian's dupload tool for this (for further info refer to man dupload and man dupload.conf). Please add the following lines to your ~/.dupload configuration file:

### X2go/DEBIAN
$cfg{"x2go-debian-sid"} = {
        fqdn => "code.x2go.org",
        login => "x2go-admin",
        method => "scpb",
        incoming => "/srv/sites/x2go.org/packages/debian/incoming/sid",
        qeueudir => "/srv/sites/x2go.org/packages/debian/upload/sid",
        dinstall_runs => 1,
};
$cfg{"x2go-debian-wheezy"} = {
        fqdn => "code.x2go.org",
        login => "x2go-admin",
        method => "scpb",
        incoming => "/srv/sites/x2go.org/packages/debian/incoming/wheezy",
        qeueudir => "/srv/sites/x2go.org/packages/debian/upload/wheezy",
        dinstall_runs => 1,
};
$cfg{"x2go-debian-squeeze"} = {
        fqdn => "code.x2go.org",
        login => "x2go-admin",
        method => "scpb",
        incoming => "/srv/sites/x2go.org/packages/debian/incoming/squeeze",
        qeueudir => "/srv/sites/x2go.org/packages/debian/upload/squeeze",
        dinstall_runs => 1,
};
$cfg{"x2go-debian-lenny"} = {
        fqdn => "code.x2go.org",
        login => "x2go-admin",
        method => "scpb",
        incoming => "/srv/sites/x2go.org/packages/debian/incoming/lenny",
        qeueudir => "/srv/sites/x2go.org/packages/debian/upload/lenny",
        dinstall_runs => 1,
};

As ~/.dupload is a Perl include file, make sure that the file's last line looks like this:

1;