Revision as of 14:29, 12 December 2008

Setting up Subversion Access

Required tools

• subversion-1.5.4 or later; download...
• ssh for committers, preferably OpenSSH 2.4 or later

SSH Setup

You need a ssh key for write access. You can skip this step if you only need readonly access.

SSH key generation

On Unix or Windows/cygwin a SSH identity (private/public key pair) is generated with:

ssh-keygen -t dsa

You'll be asked for pass phrase which protects your private key. Per default the public key is named $HOME/.ssh/id_dsa.pub.

Note that SSH keys created between September 2006 and May 2008 on Debian or Debian derived systems like Ubuntu may be insecure. Please use recent SSH tools.

If you want a dedicated identity for just OOo SVN usage, generate a specially named key pair

ssh-keygen -t dsa -f ~/.ssh/id_dsa_ooo_svn 

and instruct Subversion to use this identity (key pair) with the following configuration entry in $HOME/.subversion/config:

[tunnels]
ssh = ssh -i /home/jr93709/.ssh/id_dsa_ooo_svn

Initial Migration of Keys

Please query IssueZilla for your issue with the attachment holding your key and add it as a dependency to issue 94002. If you are a new svn user, create the issue yourself.

We will then install those keys for DomainDevelopers for read/write access to the SVN repository.

Up to now only few code committers made use of the ssh key upload for the OpenOffice.org SVN repository. Please note that your key will not be migrated without your intervention.

Ongoing Maintenance

We will continue to use IssueZilla for managing and tracking key additions and changes. Please see Submitting Your Certificate (Public Key).

Windows ssh setup with putty

To use ssh on Windows putty's ssh can be used. You need plink.exe, puttygen.exe and pageant.exe. All are available from [1]

As putty uses a different ssh key format you have to convert the private key using puttygen.exe.

Save this file for example as:

<system drive>:\Documents and settings\<user name>\Application Data\id_dsa_ooo_svn.ppk

In the [tunnels] section of the file <system drive>:\Documents and settings\<user name>\Application Data\Subversion\Config

You have to add the line:

ssh = plink.exe -i <path to you converted private key file>

Please note that spaces in the path have to be escaped using a backslash.

To be able to call an svn command you need to have the pageant.exe running. Start this and import your private key file.

On the first connection to the server the server's host key has to be added to the registry. This doesn't work within the svn command.

The following command helps to accept this key:

plink.exe -i <path to private pkey> svn.services.openoffice.org svnserve -t

Subversion Setup

Subversion documentation

The excellent Subversion documentation can be found here: http://svnbook.red-bean.com. Please use the nightly build documentation for 1.5 and later, it covers new features like merge tracking.

Server access

The OpenOffice.org repository is available at:

Repository structure

The OOo SVN repository is structured like this:

../trunk                     <= the main development line, currently master workspace DEV300 is on trunk
../cws                       <= child workspaces live here, names need to be unique
../cws/foo                   <= for example CWS foo
../cws/...
../branches                  <= future master workspaces which are not on trunk
../branches/OOO310           <= for example MWS OOO310
../branches/...
../tags                      <= milestone tags, release tags
../tags/DEV300_m32           <= for example milestone DEV300 m32
../tags/..
../dist                      <= space for distribution specific stuff
../patches                   <= space for globally useful patches
../contrib                   <= do we need this?

Setting up CWS Tooling

Please keep all your entries in your $HOME/.cwsrc for now, you'll need them if you want to work with CWSs for OOo-3.0. Just add the following line to refer to the OpenOffice.org SVN server:

SVN_SERVER=svn+ssh://svn@svn.services.openoffice.org/ooo

Example of a complete .cwsrc file:

[CWS_CONFIG]
# Network proxy for EIS connections. 
# Comment in if you need to access EIS via a proxy.
# Note: This is just for accessing the EIS database. For SVN have a look here:
# http://svnbook.red-bean.com/nightly/en/svn.advanced.confarea.html#svn.advanced.confarea.opts.servers
# Example: PROXY=http://myproxy.company.com:8080
# PROXY=

# CWS Database server (SOAP). It's possible specify to several backup server,
# currently there are none.
CWS_DB_SERVER_1=https://eis.services.openoffice.org/soap/servlet/rpcrouter

# Your CVS login (for authentication with the CWS database).
CVS_ID=<your_ooo_name>

# Your scrambled CVS password (for authentication with the CWS database).
# Take this one from .cvsrc
CVS_PASSWORD=<your_current_cvs_scrambled_ooo_password>

# OOo CVS tunnel
# Example: CVS_SERVER_ROOT=pserver:cvs_id@mytunnel.mydomain.de:/cvs
CVS_SERVER_ROOT=

# Path to the cvs binary (optional)
# Example: CVS_BINARY=/usr/bin/cvs
#CVS_BINARY=

# SVN server for OOo-3.1 child workspaces
# r/w access via svn+ssh pprotocol
SVN_SERVER=svn+ssh://svn@svn.services.openoffice.org/ooo
# r/o access via svn protocol
#SVN_SERVER=svn://svn.services.openoffice.org/ooo

Tips and Tricks

This section contains some optional steps that might optimize your usage of the Subversion repository.

Ignoring output trees

Platform output trees (unxlngi6, unxsols4, wntmsci12 etc) will show up as unversioned directories marked with a "?" in the output of svn status and other SVN commands. This is inconvenient and reduces the usefulness of these commands. In principle it's possible to deal with this in two ways:

• attach and commit a svn:ignore property to every top level directory listing all possible platforms
• add all the platforms which are usually build to the so called global ignore list

Actually the global ignore list is more of a kind of "personal" ignore list which is applied to all svn commandos which access your personal subversion configuration.

Since maintaing svn:ignore properties in about 200 directories for about 20 platforms is pretty clumsy, I suggest that we use the global ignore list for this purpose. Here is my personal ignore list, YMMV.

$ cat $HOME/.subversion/config

...
[miscellany]
...
global-ignores = common common.pro unxsoli4* unxsols4* unxlngi6* unxlngx6* unxubti8* wntmsci12* unxlngi6* unxmacxi* 
...

Detailed instructions on how to use ignore lists can be found here.

Ignoring contents of .svn when using grep

To avoid being driven insane by getting grep hits on the .svn dirs contents you can use

$ export GREP_OPTIONS="--exclude=\*.svn\*"

Speeding up svn+ssh: access by caching ssh connections

You might have notice that nearly all SVN operations are somewhat slower via svn+ssh: access than via plain (and read-only) svn: access. This is due to the ssh handshake, some SVN operations even suffer several times from the handshake overhead.

There is an easy and convenient way to get rid of this overhead by using a ssh connection cache.

The following description is taken more or less verbose from the the GCC wiki:

SSH connection caching works with OpenSSH 4.0 on all Unix look alikes, but not on Windows/cygwin. You can check your OpenSSH version with

$ ssh -V
OpenSSH_4.6p1, OpenSSL 0.9.8e 23 Feb 2007

Create a ControlPath entry for svn.services.openoffice.org in $HOME/.ssh/config

$ cat $HOME/.ssh/config
...
Host svn.services.openoffice.org
     ControlPath /tmp/ssh_ooo_control
...

Set the permissions 0600 on $HOME/.ssh/config, otherwise SSH refuses to work.

$ chmod 0600 $HOME/.ssh/config

Set up up a permanent connection to the ooo SVN server, for example right after login:

$ ssh -fMN svn@svn.services.openoffice.org

Subsequent svn commands will use the already established connection, resulting in noticeably less lag for short commands. It's also an alternative to using ssh-agent if you have protected your private key with a pass phrase.

Create a OOo repository mirror

The repository can be replicated with the svnsync tool. No special server side setup is necessary (read-only access is sufficient, please use either the svn: or http: method), but you need to make certain that the target repository can't be modified by other means than svnsync.

• First create an empty target repository:

$ svnadmin create /absolute/path/to/rep

• Implement the pre-revprop-change and start-commit hooks

$ cat /absolute/path/to/rep/hooks/pre-revprop-change

#!/bin/sh 

USER="$3"

if [ "$USER" = "syncuser" ]; then exit 0; fi

echo "Only the syncuser user may change revision properties" >&2
exit 1

$ cat /absolute/path/to/rep/hooks/start-commit

#!/bin/sh 

USER="$2"

if [ "$USER" = "syncuser" ]; then exit 0; fi

echo "Only the syncuser user may commit new revisions" >&2
exit 1

• Initialize the target repository:

$ svnsync init --username syncuser file:///absolute/path/to/rep svn://svn.services.openoffice.org/ooo

• And finally synchronize the target repository with the source repository

$ svnsync synchronize file:///absolute/path/to/rep

The full details for replicating SVN repositories can be found [here].

Reporting Problems with the Repository

The list dev@tools.openoffice.org is used to coordinate the initial migration and ongoing work on the repository and related tools. Please raise problems there first. Issues which need the attention of repository administrators should be filed in IssueZilla against the component www/openoffice.org SVN.

Read/Write access with TortoiseSVN

Please have a look at this page.

[More SVN Tips and tricks will appear here]