Skip to content

GoldVersionToDo

Jump to bottom
William Henney edited this page Oct 17, 2019 · 2 revisions

We aspire to release a gold version of the code every two to three years.
Minor releases, mainly fixing bugs, occur from time to time. 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

  • For versions c17.xx. 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.

  • For versions after c17. Make sure checksums.dat is up to date. To do this run ../scripts/generate_checksums.sh in the root of the data directory. This requires the executable ../source/vh128sum.exe which is built alongside cloudy.exe by the make script. If you build in one of the sys_xxxx directories you must temporarily copy (or symlink) vh128sum.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 save options are used in at least one of the tests. [what script does this?]

  • _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/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 ./prep-bib.sh. This is a driver script that will gather atomic data references from the Stout database into LaTeX / PDF formats, and will prepare a LaTeX table (also a PDF) with the database provenance of all species known to Cloudy. The PDFs are copied to the docs/ directory.

docs/

  • Run the script LineLabels.in to make sure that the files LineLabels.txt and SpeciesLabels.txt are up to date.

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.

  • Edit date.h to set YEAR, MONTH, and DAY to the date of the creation of the branch. We will change it to the date of the first release when that occurs. We do not change the date on xx.01 and later sub releases.

  • 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 tags

We have two types of tags, release versions and release candidates. They have different locations in the repository.

Release candidate tags

  • The name and release status is automatically created from the repository location.

  • Release candidates are located in tags / develop / and have names like c17.00_rc1, so the full path name will be tags/develop/c17.00_rc1

  • Copy the branch to this location.

Release tags

  • In the head of the branch, edit date.h to set YEAR, MONTH, and DAY to the date of the first release. We do not change the date on xx.01 and later sub releases.

  • Code exists in version.cpp to set lgReleaseBranch = true, and increment lgBetaVer from the repository name. If this is a gold copy release it will also set lgRelease = true

  • Increment version.cpp CLD_MAJOR and CLD_MINOR as needed.

All tags

  • 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 c17_01_tsuite_out_gcc640unx.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

The wiki

Links to version documentation

  • update in data/citation_cloudy.txt file used for print citation

  • update bibtex reference. Alias name should be CloudyReview so that it is picked up across Hazy.

TODO find all references to 2013 paper

Return to DeveloperPages

Return to main [WikiStart wiki] page

Clone this wiki locally