# Some basic notions about SVN

## Getting an account on &alioth;

SVN commit access requires the creation of an account on the &alioth; server. This is as simple as opening &url-alioth; and going to the account creation pages.

Official Debian developers will probably use the same login as their Debian login, but must go through the account creation process anyway. Non-Debian developers should be aware that the login they will choose on &alioth; will be followed by -guest. This has absolutely no meaning of any kind of second class citizens but is just an easy way for &alioth; system administrators to know who is an official Debian developer.

## Installing SVN

Translators and other &d-i; contributors need to install SVN (Subversion) on their system. For Debian sid or sarge users, just do `aptitude install subversion`. Users of Debian woody release may use backports from &backports;. The following entry to `/etc/apt/sources.list` may be used for this:

        deb &url-backports;debian stable subversion

Alternatively, Adam Conrad's backports may be used:

        deb http://people.debian.org/~adconrad woody subversion

These backports are not officially supported by the Debian Project. Though their maintainers are well-known and respected Debian developers, they're the only people who can guarantee that these packages are well maintained and secured.

Users of non-Debian Linux distributions will probably easily find installation sources for Subversion in their distribution packages list.

For MS-Windows users, a good SVN client is TortoiseSVN which is free software. It can be downloaded from http://tortoisesvn.tigris.org/.

Successful attempts of using TortoiseSVN for &d-i; commits have been reported. The only trick is to feed the checkout URL alone to the "svn import" command of TortoiseSVN, without the leading "svn co" part.

## Using SVN to get and commit files

Once their account is allowed to write to the project, translators and developers can download the full project source tree using the checkout commands mentioned in translators.

For doing `svn+ssh` connections (mandatory for being able to commit files later), users must have an account on &alioth; and be authorized for commit to the repository they want to checkout. Replace alioth_username by this login name before using the SVN pseudo-URLS.

`svn+ssh` connections need that you use DSA key based authentication to connect to &alioth;.

If you don't have an existing SSH keypair on your local system, you must create one with the `ssh-keygen` command.

    spongebob@mykerinos:~$ ssh-keygen -t dsa
    Generating public/private dsa key pair.
    Enter file in which to save the key (/home/spongebob/.ssh/id_dsa):
    Created directory '/home/spongebob/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    passphrase too short: have 3 bytes, need > 4
    Saving the key failed: /home/spongebob/.ssh/id_dsa.
    spongebob@mykerinos:~$ ssh-keygen -t dsa
    Generating public/private dsa key pair.
    Enter file in which to save the key (/home/spongebob/.ssh/id_dsa):
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/spongebob/.ssh/id_dsa.
    Your public key has been saved in /home/spongebob/.ssh/id_dsa.pub.
    The key fingerprint is:
    8d:6d:14:72:72:07:01:6a:85:de:97:d3:aa:b2:ee:4a spongebob@mykerinos

In the example below, the user spongebob creates a SSH DSA keypair, which is saved in a directory named `.ssh` in his/her home directory.

This keypair is protected by a passphrase. The passphrase has to be entered each time the keypair will be used to connect to a remote host. Take care to choose a non trivial passphrase.

After doing so, the public part of that keypair must be put in your account on &alioth;. For this, you need to output the contents of `.ssh/id_dsa.pub` and paste it in the relevant field of the account management page on &alioth; (&alioth-account-page;), in the section named Shell account informations, by clicking on Edit keys.

In case users have problems with SVN checkouts/commits, they can ask for help, either on IRC, &irc-channel; or by mail with the &i18n-coords;.

MS-Windows users who want to use TortoiseSVN to checkout or commit can go to the TortoiseSVN SSH HowTo page to get information about setting up TortoiseSVN to do SVN+SSH connections.

## Testing SVN commit access to &d-i; repository

A sandbox directory has been setup for developers and translators to practice with SVN before doing real work.

The sequence for testing commit access should be similar to what follows. Please note that, depending whether your SSH keys have been added to your account on &svn-debian;, you can be prompted for a password up to three times. This is because of the special authentication setup on &svn-debian;.

    cd <somedir>
    svn co &svn-di-sandbox;
    Password:
    Password:
    Password:
    .../... (checkout should happen here)

    cd sandbox
    echo "Testcommit" >foo
    svn add foo
    svn ci -m "Testcommit of a file" foo
    .../...
    svn remove foo
    svn ci -m "Remove the test file"

As stated by the `README.txt` file in this directory, please avoid commiting large files for testing as this clutters up the SVN server history.

## Core &d-i; and various levels packages repositories checkout command lines

Typical non anonymous and anonymous checkout command lines for &d-i; and related packages are listed in translators.

Below is an example of a typical checkout for the console-data package:

    user@host:~> &svn-console-data;
    TODO
    user@host:~>

After this the `console-data` directory contains all files from the package. Updating this directory later needs running the `svn update`:

    user@host:~> cd console-data
    user@host:~/console-data> svn up
    TODO
    user@host:~>

Subdirectories of a full SVN directory can also be checked out in case one want to work on specific parts. This can be very useful for &d-i; core translations as &d-i; SVN repository is very big:

    user@host:~> svn co &svn-level1; level1-po
    TODO
    user@host:~> cd level1-po/
    user@host:~/level1-po> ls -l
    total 19112
    -rw-r--r--  1 user user 369598 2005-08-18 02:56 ar.po
    -rw-r--r--  1 user user 266462 2005-08-18 02:56 be.po
    .../...
    -rw-r--r--  1 user user   1120 2005-07-17 08:17 PROSPECTIVE
    .../...
    -rw-r--r--  1 user user   2027 2005-07-31 08:54 README
    -rw-r--r--  1 user user 353752 2005-08-18 02:56 ro.po
    -rw-r--r--  1 user user    324 2005-08-16 16:30 run-l10n-sync
    .../...
    -rw-r--r--  1 user user 237996 2005-08-18 02:56 template.pot
    .../...
    -rw-r--r--  1 user user 350181 2005-08-18 02:56 xh.po
    -rw-r--r--  1 user user 335898 2005-08-18 02:56 zh_CN.po
    -rw-r--r--  1 user user 335413 2005-08-18 02:56 zh_TW.po
    user@host:~/level1-po>

If the translation file already exists, then just update the local copy:

    user@host:~/level1-po> kbabel fr.po
    .../...

(use KBabel or any other gettext utility, see gettext-tools for details about gettext files handling, editing and maintenance tools)

Once saved the modified version of the file, the status can be displayed with the `svn status` command:

    user@host:~/level1-po> svn status
    M      fr.po
    user@host:~/level1-po>

The above means that `fr.po` includes uncommited modifications. These modifications can be committed by using the `svn commit` command:

    user@host:~/level1-po> svn commit

The user will then be dropped in a file editor (either `vi` or any other file editor pointed by the EDITOR variable. The changelog message can be then filled in the editor. Saving it and exiting the editor will trigger the commit action to the SVN repository.

A more targeted commit command is also possible, as well as giving the commit message on the command line:

    user@host:~/level1-po> svn commit -m"French translation update" fr.po
    TODO
    user@host:~/level1-po>

In general, a few recommendations can be made to translators:

- Always use the `svn update` before working on a file or directory. This will minimize conflicts in case a file is changed in the repository while they work on it;

- Always use the `svn status` command before committing changes, to be sure that only relevant changes are committed.

## Changelog entries handling

When committing translations directly to SVN repositories for Debian packages (except for level 1 translations), translators must update the `debian/changelog` file accordingly.

This does not apply to level 1 translations, that is the &d-i; core packages translations. For these translations, no changelog updates are needed.

Each change in Debian packages must be documented in the `debian/changelog` file.

Below is an excerpt of the `changelog` file for &base-config;:

    base-config (2.39) UNRELEASED; urgency=low

      * Updated translations:
        - Croatian by Krunoslav Gernhard

     -- Christian Perrier <bubulle@debian.org>  Sat, 24 Jul 2004 08:14:13 +0200

    base-config (2.38) unstable; urgency=high
    .../...

This gives the following information:

- the last released version of the package is 2.38. The SVN repository currently contains the future unpublished 2.39 release;

- the only change which occurred since 2.38 is the update of the Croatian translation (made by Krunoslav Gernhard);

- the committer of this change was Christian Perrier.

Different Debian packages may use slightly different methods and styles for `changelog` maintenance. When working with SVN/CVS repositories, using UNRELEASED for the last entry is highly recommended for new unpublished changes.

Using the `debchange` utility from the devscripts Debian package for handling `changelog` entries maintenance is also highly recommended..