Version 67 (modified by gary, 2 weeks ago)

update documentation for tsuite included in hazy2

Gold Version to do List

We aim to release a gold version of the code every two years. This is the well-tested version which should be used in publications. This gives the steps that we need to take.

A major release exists as a separate branch in the svn repository, beneath the  /branches directory. The name consists of the last to digits of the year ending in "_branch". An example is "c08_branch". The branch should be created when the new release goes into beta, and no further major changes are expected.

The actual release is a tag created from the release branch, which will be in the  /tags/release directory. The tag should have a name like c08.00, where the last two digits indicate the minor release version number: 00 should be used for the first release in a new release series, 01 for the first bug-fix roll-up, etc.

Starting with the c08 release series, we will also post patch updates to each release. These have names like c08.02_pl01 (this would be the first patch to the c08.02 bug-fix roll-up release), etc. Every time a hot-fix is posted, it should be accompanied by a UNIX patch file. The procedure for creating a patch update is described on the HotFixToDo page.

For all types of releases (main release, bugfix roll-up, patch update) make sure that the variables CLD_MAJOR, CLD_MINOR, CLD_PATCH in version.h have values that correspond to the version number in the svn tags directory. For main releases and bug-fix roll-ups CLD_PATCH should be zero. If you check out the release or patch_versions tag with svn and run the code (e.g. the smoke test) it will test if CLD_MAJOR, CLD_MINOR, and CLD_PATCH are set correctly (i.e. agree with the name of the tag). A PROBLEM string will be printed at the start of the output if a mismatch is found.


Preparing the trunk for a gold version

Check that there are no blocking  tickets.

Top directory

  • check copyright year across all of source including license.txt and license_doc.txt. Don't forget the file source/license.txt [automate, generate errors for non-standard headers]
  • others.txt - this is a list of those who contributed to the code. Mail file to developers list to confirm whether it needs to be updated.

source/

  • list_headers.pl - This checks on any header files that are not used. [=> regular hygiene] It produces following output files:
    • headers.txt is a summary of all header files
    • listfiles.list with all source files using each header
  • uninclude-headers.pl - This prunes duplicate headers from source files. Dry-run first before modifying source.
  • The RemoveHeaders page documents a series of scripts that perform this code hygiene

  • todo_search.pl This makes a prioritized list of todo's, [=> regular hygiene]

creates todo_table.txt and todo_table.htm, checks no TODO criticality 0

  • doc_atomic_data.pl - This extracts all atomic data references. [=> build of Hazy]

The files created are:

doc_atomic_data_refer.txt containing new references

doc_atomic_data_refer_old.txt containing old references.

  • dense_fabden should stop with statement that it needs to be replaced [=> crash subdirectory of test suite]
  • fudge factors - check that fudge factors are used appropriately [=> test suite]
  • run doxygen

data/

  • readme_data.htm [=> move to wiki/hazy auto update] review and update
  • Make sure md5datafiles.dat is up to date. To do this run ../scripts/generate_md5sums.sh in the root of the data directory. This requires the executable ../source/md5datafile.exe which is built alongside cloudy.exe by the make script. If you build in one of the sys_xxxx directories you must copy md5datafile.exe into source.

tsuite/auto/ and tsuite/slow

  • readme_tests.htm

review

  • doc_tsuite.pl

this creates a list of all test cases, including the input commands and a description of its purpose

OUTPUT:

doc_tsuite.txt: contains a tab delimited list of the files,

doc_tsuite.htm: formatted list

create doc_tsuite.pdf from doc_tsuite.htm - this pdf is included in Hazy2

  • Run suite through on systems [=>which do we support? how to run?]

Run checkall.pl to diagnose results

Check for sims close to an assert - this is in close.txt

Check that no debugging information is present - this is listed in debug.txt

Review minor problems - these are listed in minor.txt

Do grep on "C-" to see what cautions there are. There should be no warnings, "W-"

save files

  • Check coverage run to confirm that all punch options are used in at least one of the tests.
  • CheckPunchSharp.pl

Save files should start with a header saying what the column indicate. The first character should be a sharp sign. This script lists all files that do not start with "#". This is an error, and may indicate that the header was not properly produced.

tsuite/slow/

  • run, confirm ok

tsuite/programs/

  • run the programs then check the output
  • run_programs.pl will run the set of programs with either gcc or icc.

It obtains a list of the programs from run_programs.dat

scripts/

  • Run tsuite/auto/func_lines.in to create the list of species labels that these scripts use.
  • Run perl db-ref-bib2json.pl -ni to gather atomic data references from the Stout database and place them into a json file, refs.json, in the stout directory. This file is included in the repository and the updated version should be committed. The db-ref-bib2json.pl script includes full documentation for what helper programs are needed.
  • Run perl db-ref-json2tex.pl -e -f=s -nr=32 to produce the file stout-refs.tex in the scripts directory. This file contains a LaTeX table what can be used in a paper. The file stout-refs-list.tex contains wrapper TeX, so that it can be compiled to create a stand-alone PDF file.
  • Run the command source mktable-stout-refs-list.sh to produce the standalone stout-refs-list.pdf.
  • Run perl db-species-tex.pl -e -np=4 -nr=35 -f=s ../tsuite/auto/func_lines.spclab to produce a LaTeX table, in species-db.tex, a wrapper TeX file, species-db-list.tex, and a script. The LaTeX table documents which database treats each species.
  • Run the command source mktable-species-db-list.sh to produce species-db-list.pdf.
  • Drop the PDF files into the top docs/ directory.

docs/latex/

  • In head_info.tex check that copyright and citation information, any other numbers that might have changed, are correct.
  • Update table atomic data sources.
  • Check whether in press papers in references have appeared
  • Run script "latex/CompileAll.pl" once to create PDFs in each subfolder -- you only need to run script once to get working cross-references between Hazy 1 & 2.
  • Replace any old pdf versions of hazy in the top directory with the current version and add them to the branch. The original names, as in "hazy1.pdf", must not be changed since cross references rely on them.
  • Check that no TODO's are in latex with grep -r --include="*.tex" TODO .

Creating the branch

A branch lives in the branch directory on svn and will have a name like c10_branch. The following should be changed on the branch after it is copied off from the trunk:

  • Version numbers are set at top of version.cpp. Typically it will look something like the following:
static const int CLD_MAJOR = 8;
static const int CLD_MINOR = 1;
static const int CLD_PATCH = 0;

CLD_MINOR indicated the rev level, in this case the version would be given as C08.01. The CLD_PATCH level has not been used so far. We do not update the date for sublevels; it remains at the XX.00 release date.

  • Code exists within version.cpp to determine if this is a beta version from the svn name. It will then set nBetaVer to a non-zero value, 1 for first beta. etc.
  • The flag lgRelease in version.cpp is true if this is a release. This says not to print comments about fixits, broken, todo etc. For a release branch we should set lgRelease = true around version.cpp:125-127
  • The flags nBetaVer and lgRelease should not both be set - use one or the other.
  • The flag lgReleaseBranch should be set to true around version.cpp:125-127 right after the release branch is created, it is OK to keep it true for releases.

Note that nBetaVer, lgRelease, and lgReleaseBranch will be set automatically in svn working copies. The explicit versions in the else-clause in the constructor in the file version.h are the ones that need to be modified by hand and are only used in source code that was not retrieved via svn.


Creating the tag

  • In date.h set YEAR, MONTH, and DAY if this is the first release. We do not change the date on xx.01 and later subreleases.
  • Code exists in version.cpp to set lgReleaseBranch = true, and increment lgBetaVer from the repository name. If this is a gold copy release also set lgRelease = true
  • Copy branch to tag directory on svn
  • Create release branch in git mirror repository on nublado
    cd webapps/gitweb/repos/cloudy.git/
    git log c13_branch
    git branch release/c13.xx <ID>
    

where <ID> should be replaced with the git commit number shown by git log.


Creating distribution files

The release source and data files.

Create a tarball from the releases/tags checkout. Use the following commands and sftp the file to nubado.

cd cloudy_releases
svn export svn://svn.nublado.org/cloudy/tags/release/c08.01/
tar cvfz c08.01.tar.gz c08.01
rm -rf c08.01

Never use the "file://" form in the svn command since that would expose internal information of the server!

Output files from the test suite

After running the test suite enter the tsuite directory and give the command

find . -name *.out|xargs tar cvfz c13_01_tsuite_out_gcc446.tar.gz

You may wish to remove the one output file func_fulltrace.out which is larger than all of the other output files together. Then copy this to the nublado site.


The release

  • post on front page of web site
  • make discussion group announcement

Return to DeveloperPages

Return to main wiki page

Return to  nublado.org