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.
- 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.
- 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.
- 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
- 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.
this creates a list of all test cases, including the input commands and a description of its purpose
doc_tsuite.txt: contains a tab delimited list of the files,
doc_tsuite.htm: formatted list
- 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-"
- Check coverage run to confirm that all punch options are used in at least one of the tests.
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.
- run, confirm ok
- 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
- 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.
- 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.
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.
- post on front page of web site
- make discussion group announcement
- update DownloadLinks page
Return to DeveloperPages
Return to main wiki page
Return to nublado.org