Updating a Baselibs Component

Process of Importing A New Component to Baselibs

This example document will detail the process that was used importing NCO 4.2.3 into GMAO Baselibs.

Set up the new tag

In this case, we were adding NCO 4.2.3 to GMAO-Baselibs-3_3_0. So, the "internal" tag we went to was 3_3_1. In a temporary directory (say, ImportCheckout) you checkout Baselibs and tag relative so you know where you started from. You also make sure the tag you're making doesn't exist:

  $ cd /gpfsm/dswdev/mathomp4/Baselibs/ImportCheckout
  $ bcvs co Baselibs
  $ cd Baselibs/src
  $ bcvs tag -r GMAO-Baselibs-3_3_0 Internal-3_3_1-before-NCO-4_2_3
  $ bcvs tag -d Internal-3_3_1

Unpack the new library

First, move to a directory that can contain your "new import",

  $ cd /discover/swdev/mathomp4/Baselibs/NewImports

untar the package (from http://nco.sourceforge.net/#Source),

  $ tar xzf nco-4.2.3.tar.gz

and move into the new directory directory:

  $ cd nco-4.2.3/

Import the new package

First, do a dry-run import of the package (note the -nq):

  $ bcvs -nq import -kk -m 'MAT: import NCO 4.2.3 retrieved 2012-NOV-13 from http://nco.sourceforge.net/#Source' Baselibs/src/nco NCO release-4_2_3

If everything looks okay, then actually import the package:

  $ bcvs import -kk -m 'MAT: import NCO 4.2.3 retrieved 2012-NOV-13 from http://nco.sourceforge.net/#Source' Baselibs/src/nco NCO release-4_2_3

     39 conflicts created by this import.
     Use the following command to help the merge:

        cvs -d :ext:mathomp4@progressdirect:/cvsroot/baselibs checkout -j<prev_rel_tag> -jrelease-4_2_3 Baselibs/src/nco

Note that this command provides helpful information on how to merge this package. You'll want to make a note of the previous release tag. The best way to find this out is via tkcvs, in my opinion.

Merging the new package into the tree

First, check out a new Baselibs tree:

  $ cd /discover/swdev/mathomp4/Baselibs
  $ mkdir NewBaselibs
  $ cd NewBaselibs
  $ bcvs co -kk Baselibs/src
     <snip checkout>
  $ bcvs -q checkout -kk Baselibs/src/nco

Note, I'm not too sure why you do the package checkout right after the full Baselibs checkout (which would checkout the HEAD), but Denis always did this. It can't hurt, though. Note also that we checkout ignoring keywords (-kk) which always makes merging easier.

Then, checkout/update to new release:

  $ bcvs -nq update -kk -jrel-4_0_3-20100627 -jrelease-4_2_3 Baselibs/src/nco

and remove -nq and run again once satisfied. Note: Denis used this style of command, but CVS prefers checkout. Unsure which is better.

Move into the new package directory:

  $ cd Baselibs/src/nco

and check for conflicts:

  $ bcvs -nq upd -kk | grep -r '^[C|M]'
  
  cvs update: New directory `autom4te.cache' -- ignored
  cvs update: New directory `debian' -- ignored
  cvs update: New directory `src/nco++/.deps' -- ignored
  M doc/ANNOUNCE
  M doc/ChangeLog
  M doc/MANIFEST
  M doc/Makefile.in
  M doc/README
  M doc/TODO
  M doc/VERSION
  M doc/debian.txt
  M doc/i18n.txt
  M doc/index.shtml
  M doc/man_end.txt
  M doc/nco.dvi
  M doc/nco.html
  M doc/nco.info
  M doc/nco.pdf
  M doc/nco.ps
  M doc/nco.texi
  M doc/nco.txt
  M doc/nco.xml
  M doc/nco_news.shtml
  M doc/nco_src_frg.txt
  M doc/opendap.sh
  M man/Makefile.in
  M man/ncap.1
  M man/ncap2.1
  M man/ncatted.1
  M man/ncbo.1
  M man/ncdiff.1
  M man/ncea.1
  M man/ncecat.1
  M man/ncflint.1
  M man/ncks.1
  M man/nco.1
  M man/ncpdq.1
  M man/ncra.1
  M man/ncrcat.1
  M man/ncrename.1
  M man/ncwa.1

Note in this case that no conflicts were found. If there were conflicts, you should resolve them. When in doubt, I suggest always using only what the new package contained. The only exceptions might be in Makefiles or other files that might have been edited by Denis or other maintainers to get it to build with the other Baselibs. But, if at all possible, go with the stock library.

Once all is good, commit the changes:

  $ bcvs commit -m "MAT: merge new NCO release 4.2.3, no conflicts found"

Tagging your new release

To make your new tag, first do a relative tag at the src/ level:

  $ cd ..
  $ bcvs tag -r GMAO-Baselibs-3_3_0 Internal-3_3_1

Then, for safety's sake, untag the new library and retag the against the new vendor release tag:

  $ cd nco/
  $ bcvs tag -d Internal-3_3_1 
  $ bcvs tag -r release-4_2_3 Internal-3_3_1 

Next, edit the usual metafiles (Changelog, CONTENTS, and VERSION) as well as any needed make system changes and commit those on the HEAD. Then, push your new tag on those files:

  $ bcvs tag -F Internal-3_3_1 ChangeLog CONTENTS VERSION

Verify new tag

The final step is to checkout the new tag and build the Baselibs per usual. My first step is to usually do a cvscmp against the old tag to make sure everything looks sane. I then like to do a diff -r between the updated library and the stock package that was downloaded from the web. Hopefully, all is well.

If everything works, you can then delete your "before" tag and if all really works, rename the Internal tag with an official GMAO-Baselibs tag.