Preparing a software project for release

BEWARE: the procedures described here apply only to projects maintained in SVN. If you wish to release a project maintained in Git (i.e. the vast majority of LHCb software), a different procedure applies

This wiki explains the procedure to be used by software release managers to prepare a project for release. It assumes the project is in SVN. Software release procedures are discussed in the lhcb-release-managers E-group, all software release managers should be members of this group

Introduction

The procedure described below is a suggested procedure. Mandatory steps are highlighted in RED. In the code examples below, we assume you are releasing project LBCOM version v99r11.

There are two different methods of preparing the release, these are interchangable and it is advisable to be familiar with both. Either you can use a GUI-based method, revolving around the Tag Collector and Eclipse, or a command-line based method which requires a lot of disk space and usually more time.

Prerequisites

  • You are assumed to be familiar with svn.
  • You are assumed to be familiar with our project/package structure.
  • You are assumed to already have been a developer of the software you are now releasing. Now you are a manager.
  • You will have read and understood the SVNUsageModel
  • You are familiar with, and adhere to, all the SVNUsageGuidelines

Tools and terms

Term Explanation
the head The most recent software with all committed modifications. Also known as the trunk in svn.
branch A development offshoot which is not compatible with the head and must be handled carefully.
a tag A persistent coherent snapshot of software at a given point in time. A versioned piece of software indicated by the tag name.
an official tag A tag with a name of the form vXrY.
a user tag A tag with the form <user>_yyyymmdd
tagging within the release system, this is the action of creating a tag or set of coherent tags.
tag collecting The collecting of changesets and modifications which are expected to go into a tag. Tag collecting is not tagging.
the tag collector a website interface to a database where revisions are collected before official tags are made

Tool Explanation Example
svn info Find information about a local checked out package such as the last person to modify it and the svn path svn info
getpack Checkout from the repository by package name, no need to know the full path to the repository. getpack -rH LHCbSys head
tag_package Create a tag of a package. Usually this means copying from on svn location to another tag_package MyHat/MyPackage me_20110907
svnCheckTags Check that the packages and tags requested in a given requirements file or project.cmt exist. Can also compare the contents with the trunk. svnCheckTags Rec v12r0 --diffs
svnDiffTags Compare the contents of two tagged versions of a package or project and its dependent packages svnDiffTags Rec v11r0 v12r0
cmpPackageWithTrunk compare the content of a checked-out (and modified) version of the software with the trunk cmpPackageWithTrunk --all
getNightlyRefs copy any new reference files from a specific nightly slot to a local checkout so that you don't need to re-run the tests yourself. getNightlyRefs lhcb-prerelease

Test Driven Development

Don't forget about testing any changes which go into production software, we try and encourage TestDrivenDevelopment, where behavioural tests are enshrined in our QM-Test framework.

Option 1: Tag Collector and Eclipse

The Tag Collector has a lot of release-manager helper features.

Eclipse is an integrated set of IDE's which provides the same look-and-feel to many different IDEs and functions. It also has a complete SVN interface which is very user-friendly. To configure eclipse correctly for LHCb see EclipseConfiguration.

Before you try and use eclipse, it's a good idea to understand a bit about it, get familiar with the most basic operations, such as opening different perspectives, looking through the Gaudi/LHCb svn repositories, etc.

Checks before tagging (lost tags)

Description: Video Example:

You can check if anyone has made a change which has not appeared on the tag collector. Login to the tag collector and go to Lost Tags. Type and choose from the auto fill the name of the package. If someone has made a modification, but not put it on the tag collector it will appear in the list of "Missing Tags".

You can then select the radio button to see what the revisions were which were not requested in the tag collector, and then either add it to the tag collector, or more likely, contact the author to request clarification. The example on the right is for HLT and Moore v20r2.

Tagging

The project has to be correctly tagged in order to be ready for release. A project release consists of a set of constituent packages each of which is tagged. An SVN tag is simply a copy of the package on the 'trunk' to a 'tags' directory. The <Project>Sys package the files project.cmt, CMakeLists.txt, have to be tagged with the project <version>. The list of constituent packages and tags to be released is found in the <Project>Sys/cmt/requirements file.

1: Update the project dependencies and tag the <PROJECT> package

Description: Video Example:

Firstly, you need to make the project structure inside Eclipse. The example video on the right does these steps for HLT, in the old cmt-style tagging.

(a) Switch to the SVN view and navigate down to the project directory.

(b) Checkout the project trunk directory (non-recursively) and the contained cmt directory

(c) make any needed modifications to the files project.cmt and CMakeLists.txt.

(d) Then select the modified files (CTRL+left click) then right click on the selection, and go to Team->Commit, to commit them to the trunk.

(e) Copy the cmt directory from the trunk, then. Navigate to the tags/PROJECT directory, and make a new sub directory for LBCOM_v99r11.

(f) Then paste the cmt folder into this directory.

(g) Repeat the copy&paste steps for all the files in the project directory (e.g. CMakeLists.txt, Makefile,...) and for the directory cmake.

2: Tag all the packages that are updated for the release. The packages to be updated should be documented in the LHCbTagCollector.

Description: Video Example:
Next you should tag all the packages using the TagPackage page of the tag collector. For each modified package on the tag collector, fill out this form. The example on the right is given for tagging an HLT release. Note that it takes only a few of minutes to etag an entire project this way.It autocompletes, so

(a) first select the package name, then the project will be suggested.

(b) Click in the version box and it will be filled for you, the requirements file and release notes will be downloaded from SVN.

(c) You can freely modify the requirements and release notes, are free to choose the name of the next version,

(d) Insert the tagging comment automatically by clicking the button.

(e) Once you are satisfied, choose submit to commit your changes to SVN and tag the package with the version you have given.

3:Update the <Project>Sys package

Description: Video Example:
Then there is only one package left to modify, the Sys package, in this case you want to create e.g: "LbcomSys v99r11", which can be easily achieved by having the Tag Collector main page open in one window, and the Tag Package script open in another.

(a) Display the project you are interested in in one window

(b) Open the tag package for the sys package in another window

(c) Update the requirements file with the tags you just made in the above step.

(d) Edit the release notes to give all the changes and new tags you have incorporated in this version

(e) click submit, and that's you done.

Option 2: Command-line based

Tagging

The project has to be correctly tagged in order to be ready for release. A project release consists of a set of constituent packages each of which is tagged. An SVN tag is simply a copy of the package on the 'trunk' to a 'tags' directory. The <Project>Sys package the files project.cmt, CMakeLists.txt, have to be tagged with the project <version>. The list of constituent packages and tags to be released is found in the <Project>Sys/cmt/requirements file.

Note that the procedure applies to projects. For data packages, it's enough to just tag the package, as in the last step.

  1. Go to a working directory with lots of quota (typically a directory on a local disk of your machine)

  2. Update the project dependencies and tag the <PROJECT> package
    • check out the HEAD of the complete project
      getpack -P -H LBCOM HEAD
      cd LBCOM/LBCOM_HEAD
    • edit cmt/project.cmt and CMakeLists.txt to update the dependencies of the project
    • commit and tag with the new version number (for example v99r11):
      svn commit -m v99r11 cmt CMakeLists.txt
      tag_package -P Lbcom v99r11
      
  3. Tag all the packages that are updated for the release. The packages to be updated should be documented in the LHCbTagCollector.
    • Take the appropriate section of the tag collector page and, for each package mentioned in there:
      cd <theHat>/<thePackage>
      svn info
    • If the Revision corresponds to the revision given in the tag collector, all is well, the package trunk corresponds to the version that should be released. If the Revision is different, you have to decide whether you want to include them in the release - either unilaterally or in consultation with the author of the changes. You can check the differences with svn diff -r <someRevision>, where <someRevision> is the revision with which you want to compare, for example the revision given in the tag collector. If all is well,
    • In doc/release.notes, add the line with release version number and date
      • If already added by the package manager, check that the version number is correct, and that they haven't moved the line from a previous release - yes I happens!)
    • Check that cmt/requirements and CMakeLists.txt contain the new version number
      • If not, update it
    • commit and tag with the new version number:
      svn commit -m <theNewOfficialTag>
      tag_package Hat/Package
      (the tag is guessed from the content of cmt/requirements and CMakeLists.txt)
  4. Enter what you have tagged on the collector. Following your tagging, please commit all changes to the LHCbTagCollector, this is complicated, and much easier if you just do the tagging through the collector in the first place.
  5. Update the <Project>Sys package
    cd LbcomSys
    • in cmt/requirements update the version numbers of all the updated constituent packages
    • in cmt/requirements and CMakeLists.txt update the <Package>Sys version number if not already done. The version must correspond to that used to tag the <PROJECT> package
    • in doc/release.notes and add, for each of the modified constituent packages, a summary of the release notes of the package.
    • Commit and tag
      svn commit -m v99r11
      tag_package LbcomSys

Mandatory: Checks prior to release

Description: Video Example:
  1. Check that the whole project is correctly tagged
    • It is now possible to do this directly through SVN:
      svnCheckTags Lbcom v99r11
    • This will print warnings and errors if tags are missing.
    • In case of missing or incorrect tags, you may have to retag the Sys package

  2. Check that nothing has been missed from the release
    svnCheckTags Lbcom v99r11 --diffs
    This gives you any files that are in the trunk of SVN but not included in the release tag. This is either because you made a mistake in the tagging above, or because the changes were not included in the tag collector, either on purpose or by accident. Usually this is avoided by checking the LostTags of the TagCollector before this stage. In the latter case decide if the changes should anyway be included - either unilaterally or in consultation with the author of the changes. You may have to retag.

Add a new version of the project to the tag collector

Once you have tagged the project, you should avoid having new package revisions added to the project in the tag collector. Create a "New Project" where people can add new revisions, and edit the description of the project to be released to say that the project is tagged and frozen and no new package revisions should be added

Mandatory: Nightly test of the software

The tagged software should be built and tested at least once in the LHCbNightlies build system.

Description: Video Example:
(a) Go to the nightlies page

(b) spawn the configuration editor

(c) Add your project into the lhcb-prerelease slot. Usually this means updating the existing entry by double-clicking the version. If the "Disabled" flag is set to true, you should change it to false, so that the new project gets built.

N.B. If your package, or its tests, depend on a data package, check that the nightlies are picking up the latest version (or even the SVN HEAD if needed). See here how data packages are made available in the nightlies

Often the nightly tests will fail in trivial ways which are cured by simply updating the test references. You can use the getNightlyRefs script from Lbscripts to copy the references to some local checkout without needing to re-run the tests yourself using rsynch to add the .new files to some local checkout. getNightlyRefs has its own help, and does not work outside the CERN firewall. Having carefully checked and updated references, you can retag the affected packages before the release request.

Writing the release notes

The release notes for different projects follow different models and have different levels of verbosity. The release managers are at liberty to determine the verbosity, but all major changes which will modify the content of the output files, the look and feel of the program, or the user experience should be well-documented.

One simple way to compile a list of all the changes is to use the tag collector 'display.html', which provides a static URL for the tag collector entries for that release

This URL can be inserted in the usual release.notes to reduce the amount of writing, and speed up the release procedure for you. It has the added advantages that the changesets in SVN, and bug reports are linked directly, so persons looking through the release.notes can get a very clear picture of what has happened.

  • In the case you have used the tag collector to collect and tag all included packages, you can place the fixed url for the changes into the release notes, rather than writing them yourself.
  • In the case you haven't used the tag collector, or not all the changes are in the tag collector, then you are at liberty to write your own subsequent comments.
  • In either case there will be some release notes you'll want to add by hand anyway, to describe the purpose of the release and highlight major changes.

Add compatibility information to Ariadne

This step applies only to the following projects: Gauss, Boole, Moore, Brunel, DaVinci. All the rest are not (yet) tracked by Ariadne. The procedure has to be done from LXPLUS, or any SLC machine with Kerberized CERN login and 'cern-get-sso-cookie' package installed (note that access to Ariadne from SLC5 and earlier is not supported any more). Essentially, what has to be done in this step is insertion into the Ariadne system of a new application version and of all its relationships to other Ariadne metadata entities that it has to have.

Below the most frequent use cases are listed:

  1. Adding an application version WITHOUT compatibility relationships (i.e, incompatible with everything):
    This covers the simplest case of adding a new application version, which is incompatible with everything known by that time (see the flavor list of tracked entities at the bottom of the section). See below the command line on an example of Brunel vXrY:
          ariadne add application:Brunel:vXrY
    The latter command line will add a standalone 'application' node to the knowledge graph of the Ariadne system which, in essence, is not related in any way to other Ariadne nodes. This, though, doesn't prevent to add any relationships to it later on.
  2. Adding an application version WITH compatibility relationships, IDENTICAL to those of another application version:
    If a new application version has to inherit all relationships from an existent application version (which is what is wanted in most of the cases) the following command line will do the job:
          ariadne add application:Brunel:vXrY =application:Brunel:vXrZ
    The instruction in the second argument, uses the '=' operator to specify the node where relationships have to be cloned from.
  3. Adding an application version with NEW set of compatibility relationships:
    This is the most non-trivial use case. Let's say one needs to clone all relationships from an existent node, then add relationship to, e.g., Reco20 reco type, and remove another relationship to 2012 detector type. To accomplish this two extra instructions, using '+' and '-' operators, have to be given:
          ariadne add application:Brunel:vXrY =application:Brunel:vXrZ +reco_type:Reco20 -detector_type:2012

In all the above mentioned examples the following metadata entities may be specified:

      application:NAME:VERSION
      tag:PARTITION:TAGNAME
      reco_type:NAME
      sim_type:NAME
      detector_type:NAME
Tip, idea It is usually useful to add a -d option to all the command lines above to see what exactly the tool is performing. To see the command-line tool help issue ariadne add -h.

Mandatory: Trigger the release build and request deployment

Once you are satisfied that the release is ready, follow the instructions at ProjectRelease#For_Release_Managers to trigger a release build and request its deployment.

Clean up the tag collector

Once you have made the release request, you should "hide" the project from the tag collector, by clicking on the red cross to the right of the project heading and answering OK to the following questions. Before you do so, check that no-one has added new package revisions after you tagged the project. If any were added, move them to a newer version of the project, using the "Edit" button next to the package revision entry.

Document the release

The doxygen documentation of the project is made automatically by the release procedure. But the project release pages (e.g. http://cern.ch/LHCb-release-area/DOC/lbcom/) have to be updated by hand, see instructions here

Common problems/mistakes:

Common problems are documented in the SVNUsageModel, hopefully all will be protected by pre-commit-hooks in the future.

Retagging:

Often mistakes will be inadvertently made, meaning a tag was not quite what it seemed.

  • Release managers have sufficient power over the repository to be able to retag existing packages.
  • But, this is a dangerous action, It is very easy to accidentally remove a tag from a different release.
  • Take great care when tagging and retagging packages

Retagging involves removing the existing tag manually, using eclipse or on the command line, and then tagging the package with the same version as you would normally.

  • e.g. removing
    svn rm svn+ssh://svn.cern.ch/reps/lhcb/Lbcom/tags/LbcomSys/v99r11 -m 'removing v99r11 tag'
    

Branching:

Branching is required whenever a developer needs to modify code in an incompatible way with the existing head. This should always be discussed with the release manager.

Tagging from a branch must at the moment be done on the command line, because all our release tools are not well setup to handle this. See SVNUsageGuidelines#Working_with_branches

Special procedures

Prepare a patch release just to use a different base project

If there is the need to pick up a bug fix in a base project and the overriding of a package is not enough (e.g. a change in a header of GaudiKernel), and the release that need a patch is not the latest one (trunk), it is necessary to branch the project and its container package.

Branch and modify the project

You can use the branch_package with the option -P:
branch_package -P LHCb -T v34r3 v34r3b
Check out the project file from the branch
getpack -P LHCb v34r3b
Edit and commit the changes
emacs LHCB/LHCB_v34r3b/cmt/project.cmt
emacs LHCB/LHCB_v34r3b/CMakeLists.txt
svn commit -m "use a different version of Gaudi" LHCB/LHCB_v34r3b/cmt/project.cmt LHCB/LHCB_v34r3b/CMakeLists.txt
Tag the project
tag_package -P LHCb -B v34r3b v34r3p1

Branch and modify the container package

Again, use the branch_package script (without -P)
branch_package LHCbSys -T v34r3 v34r3b
Check it out
getpack LHCbSys v34r3b
Edit the version in the requirements and the release notes, then commit.
emacs LHCbSys/cmt/requirements
emacs LHCbSys/CMakeLists.txt
emacs LHCbSys/doc/release.notes
svn commit -m "updated version" LHCbSys
Then tag
tag_package LHCbSys -B v34r3b v34r3p1

Test

Try the newly created tag by checking it out (remove the temporary directories you created before, working on the branches):
getpack --batch --no-config -Pr LHCb v34r3p1
Optionally, you can build and run the tests:
cd LHCB/LHCB_v34r3p1
make -j 20 CMTEXTRATAGS=use-distcc,no-pyzip tests

-- MarcoCattaneo - 23-Jul-2010

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng EclipseCheckout.png r1 manage 115.2 K 2010-10-27 - 23:43 RobLambert  
PNGpng EclipseCommit.png r1 manage 151.2 K 2010-10-27 - 23:43 RobLambert  
PNGpng EclipseTag.png r1 manage 155.7 K 2010-10-27 - 23:44 RobLambert  
PNGpng LostTags.png r1 manage 50.9 K 2010-10-27 - 23:44 RobLambert  
PNGpng NightlyEditor.png r1 manage 90.6 K 2010-12-17 - 12:52 RobLambert NIghtly editor screenshot
PNGpng TagPackage.png r1 manage 72.4 K 2010-10-27 - 23:44 RobLambert  
Edit | Attach | Watch | Print version | History: r48 < r47 < r46 < r45 < r44 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r48 - 2016-08-08 - MarcoCattaneo
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    LHCb All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback