Using Subversion (svn) in LHCb
The LHCb code is kept in a
Subversion
repository
(currently being migrated from CVS). This page is intended for LHCb Subversion users. Instructions for LHCb Subversion librarians are available on
SubversionSupport.
For instructions about the usage of the CVS repository, look at
CVSUsageGuidelines.
Table of Contents
Accessing Subversion
Web access
- The LHCb, Gaudi and Dirac repositories are world readable and browsable via the two web interfaces and a statistics page
The layout of the repository is based on the rules outlined in the
Gaudi twiki.
Installing the Subversion client
The Subversion command line client
svn
is available in all Linux distributions with names like
subversion
or
subversion-client
. It is available by default on
lxplus5
nodes, but it might not be installed on other machines, but you can easily find on the web how to install it for your distribution.
For Windows,
MacOS (and for Linux distributions that do not have it packaged) you can find
the sources
and
pre-compiled distributions
linked from the
official Subversion web site
.
Several
graphic clients to Subversion
are available too.
On the LHCb Windows Terminal Server we install the
CollabNet command line client and the
TortoiseSVN
graphic client (a command line client is mandatory to be able to use
getpack
).
Setting up read access
Detailed instructions about how to configure the access to the Subversion repository are provided by IT in the
SVN How-To
. You can find instructions for
Linux
and
Windows
.
Note: To enable the ssh tunnel for the command line client on Windows (URLs of the form
svn+ssh://
), you may need to add the line
ssh = $SVN_RSH "C:/Program Files/TortoiseSVN/bin/TortoisePlink.exe"
to the
[tunnels]
section of the subversion client configuration file (either the user or the global one), see
the Subversion book
for details.
Getting write access
To get write access to LHCb Subversion repository, go to the e-group
lhcb-svn-writers
and register the account you want to use when accessing the Subversion repository. A mail will be sent automatically to the librarians that will add you to the group.
Note that when you register to the e-group
lhcb-svn-writers
, you will receive the emails sent on the
lhcb-core-soft mailing list
.
Connecting with a different user name
For windows, it is quite simple. You just have to change the autologin name in the "svn.cern.ch" session. You can do it by loading the session in putty and change the username in the Connection->Data section as described in the
CERN SVN How-To
.
For Linux/MacOSX, this is a little bit different because on these platform the username is always forwarded to the ssh connection. In order to change the username that ssh is using, you have to modify or create the ssh configuration file ~/.ssh/config. In that file, the entry for svn.cern.ch should look like:
Host svn.cern.ch svn
User myusername
Protocol 2
ForwardX11 no
IdentityFile ~/.ssh/id_rsa
Host isscvs.cern.ch
User myusername
Protocol 2
ForwardX11 no
IdentityFile ~/.ssh/id_rsa
where "myusername" is the name you want to use for the ssh authentication. Note that the entry for
isscvs.cern.ch
is needed since the latest getpack also queries this server.
To be noted that this procedure for the setting of the user name prevents the explicit embedding of the user name in the URL of the repository. There is a problem in the release areas and distribution kits if a given user name is hard-coded in the URL. There should be no explicit user name.
Kerberos authentication (Linux/!MacOSX)
It is possible to use the Kerberos V token to connect to the Subversion server instead of the ssh key, simply modifying the content of the .ssh/config file as
Host svn.cern.ch svn
User myusername
GSSAPIAuthentication yes
GSSAPIDelegateCredentials yes
Protocol 2
ForwardX11 no
IdentityFile ~/.ssh/id_rsa
Host isscvs.cern.ch
User myusername
GSSAPIAuthentication yes
GSSAPIDelegateCredentials yes
Protocol 2
ForwardX11 no
IdentityFile ~/.ssh/id_rsa
as explained in the
SVN How-To
.
getpack
After these settings, you are able to get the code (
check out
) from the repository:
svn co svn+ssh://svn.cern.ch/reps/lhcb/AProject/trunk/MyPackage
svn co svn+ssh://svn.cern.ch/reps/lhcb/AProject/tags/MyPackage/v2r3 MyPackage
on Linux, MacOSX or Windows, however, this is not however the usual way we check out packages in LHCb.
The tool
getpack
simplifies users' life taking care of details like the presence of several repositories and the project that contains the package. It is also able to do a recursive checkout according to the CMT dependency.
Note that to be able to use
getpack
you must be able to connect correctly to the Subversion repository without being asked for the password, so be sure that you have the correct configuration explained above.
For backward compatibility with the pre-svn version of
getpack
, if the environment variable
GETPACK_USER
is defined, getpack will embed the value of that variable in the URL when checking out the code. Since it is not a good idea, check that you do not set that variable and use the above instructions to use the correct username when accessing the repository.
Guidelines for SVN actions in LHCb
Creating a new package
If you wish to create a new package and add it to Subversion, follow the guidelines in
CreateNewPackageSVN.
Guidelines for SVN commit
- Commit often, but commit only code that compiles and runs (i.e. that does not prevent the configuration of the application).
- Before changing any released package, you should discuss the changes with the package owner (whose name usually appears in the cmt/requirements and doc/release.notes files). It is usually a good idea to inform the appropriate mailing list of the planned changes.
- If this is the first modification to be committed after a release:
- Increment the version number in the
cmt/requirements
file
- Increment the major version (
v
) if the change is backward incompatible (change in interfaces, major change in behavior)
- Increment the minor version (
r
) for a new feature or a bug fix
- Document each commit in the file
doc/release.notes
- Give a brief but meaningful description of the changes ("minor fixes" is not good enough)
- But no need to document the fix to the fix that you committed a few hours ago
- Please keep the lines short, max 80 characters per line, carriage return to a new line if necessary.
- Add your comment above the release separation line (done for you by the <insert> key in the LHCb emacs customisation
) ! 2009-12-15 - Marco Clemencic - This is the comment for the latest commit, do not touch anything below this line. !================== GaudiConf v10r9 2008-06-04 ======================== |
- Check what you are about to commit against the repository:
svn status -u
This will list the files that have changes with respect to the versions in the repository. The type of difference will be marked with one or more letters. The most common are: M for changes in your copy, ? for new files, * for files that have a new version in the repository, C if there are conflicts between your changes and the ones in the repository, ! for files removed. The complete list of letters can be found in the SVN documentation
. Once you're sure of your changes, you can call svn update
(or svn up
) to synchronize the working copy with the changes in repository.
- Add an entry to the LHCbTagCollector using the number that was printed by
svn
after the commit as reference. If you want to use a "user tag" as it was done with CVS, follow the guidelines for tags
- The next day, check that your commit has not broken other packages
- Check the nightly builds
the day after your commit
- Fix any packages that were broken by your commit (or ask the package owner to do it)
Guidelines for tags
Tagging in Subversion, if you are used to another version control system, may appear strange. The concept of
tag and
branch are not available in Subversion, but they can be easily emulated using a convention, thanks to the ability of Subversion of remembering the history of the whole repository (including directories).
The standard convention used in almost all the projects hosted on Subversion (a notable exception being
CMT
) is based on the presence of three directories called
trunk
,
tags
and
branches
. The
trunk
contains the main line of development of your code.
tags
and
branches
contains copies of the
trunk
with symbolic names (like
v1r2
or
2.3.4
). There is no technical difference between
tags
and
branches
, but the convention is that you are not supposed to commit changes to a file in the tags directory.
The convention used for the repository layout in LHCb is described in detail in
GaudiSVNRepository.
The guidelines for tagging in LHCb were
presented
on 18th June 2008 (33rd LHCb software week)
- It is recommended to use a tag of the form
<username>_<yyyymmdd>
where <yyyymmdd>
is the date of the commit. If you have to create more than one user tag during the day, you can append a lowercase letter (starting from a
) to distinguish them. To tag the repository as of a certain date (e.g. now) do (note: you can use svn info | awk '/^URL/{print $2}'
to get the URL of the package you are using)
svn cp svn+ssh://svn.cern.ch/reps/lhcb/Brunel/trunk/Rec/Brunel svn+ssh://svn.cern.ch/reps/lhcb/Brunel/tags/Rec/Brunel/marcocle_20091215
or to tag according to what's presently in your directory, do in your directory (e.g. Rec/Brunel
):
svn cp . svn+ssh://svn.cern.ch/reps/lhcb/Brunel/tags/Rec/Brunel/marcocle_20091215
See GaudiSVNRepository for a description of the tags conventions in the LHCb Subversion repository.
- Do not use an official tag of the form
vxry
- Add the new tag to the tag collector (how?) to inform the release manager of the new tag if you would like it include in the next official release.
How to alter a tag
Modifying the content of a tag is
always a
bad policy.
If you really have to do it because after a tag you realized you forgot to do a commit and it is a "user tag" then it is better to create a new tag.
To retag you have to delete the tag you created with something like:
svn rm svn+ssh://svn.cern.ch/reps/lhcb/Brunel/tags/Rec/Brunel/marcocle_20091215
then re-create the tag with the instructions in the previous section.
Subversion documentation
Basic SVN commands
A list of basic SVN commands can be downloaded from
http://ariejan.net/svncheatsheet
.
A summary of SVN commands for CVS users can be found in the
Gaudi twiki.
Some simple instructions to migrate an existing CVS checkout to SVN are available at
HowToMigrateACvsCheckoutToSvn.
Subversion manual
The complete manual is available from
http://svnbook.red-bean.com
Instructions for LHCb librarians
Instructions for LHCb Subversion librarians are available at
SubversionSupport.
--
MarcoClemencic - 15-Dec-2009