Suggested procedure for merging develop to master

In GKW development model there are two perpetual public branches of GKW (see git docs):

• master: points to a recent, stable, and well tested version of the code, recommended for users.
• develop: latest working version, where all new work is merged, prior to becoming master. Must pass standard test cases, but changes often.

When to update master

Master should be updated (this defines a "new release") if any of the following conditions are met:

• There are significant new stable features or bugfixes present in develop
• develop is more than 100 commits ahead of master
• 6 months has passed since last master version (assuming active developments)

Steps to update master

The list below is not very formal, and suggested changes are welcome - we don't want to make it too burdensome: The aim is to guarantee that master will always compile and pass the tests (everywhere, with all compilation possibilities), but we cannot define any procedure that will guarantee it is bug free.

• Announce imminent planned release to developers. Try to encourage all complete feature branches to be merged into develop, with test cases added / modified where needed.
• After everything planned is merged, use develop for some real runs. Ask others to.
• Check that the code compiles in serial, parallel, single precision, double precision, with and without various libraries, with debug options, with as many compilers as you can find on your development machine.
• Check that the expected tests pass in each compilation case, or make an informed decision about why they shouldn't. In order to test even more files it is a good idea to run gkw_run_tests --compare-to-serial.
• Check compilation and run tests on Helios (or ask someone else to)
• Ask someone else with a different machine and different compiler to compile and run the tests on develop.
• Check that the manual builds
• Update the file UPDATES, summarising the improvements.
• Merge develop into master, check the merge went correctly by examining the history, test again, push.
• Tag master with the next incremental tag, use an annotated tag following previous conventions: Repeat the new info from the UPDATES file and summarise the testing results. Push the tag (does not happen automatically)
• Merge master into develop, to propagate the tag, push.
• Compile and upload the manual to https://bitbucket.org/gkw/gkw/downloads and http://www.gkw.org.uk

Using the test script effectively

In order to make the most of the existing testcases, one can use the test script gkw_run_tests like in the following code listing which uses btppx configs. Note though, that this produces a lot of expected or false positives (i.e. complaints about very small differences or completely changed output formats) and the log output must be skimmed manually.

#!bash

#!/bin/bash

cd $GKW_HOME/tests/standard

gkw_switch_testcase_parameters <<EOF
io_format
CONTROL
'ascii'
y
EOF

gkw_switch_testcase_parameters <<EOF
io_legacy
CONTROL
.true.
y
EOF

gkw_switch_testcase_parameters <<EOF
io_testdata
CONTROL
.true.
y
EOF

rm -rf $GKW_HOME/tests/more
gkw_run_tests --gkw-generate-parallelisations=$GKW_HOME/tests/more

gkwmake clean
gkwmake -j DEBUG=on OPTFLAGS=off
gkw_run_tests --serial  $GKW_HOME/tests/standard $GKW_HOME/tests/more
gkw_run_tests --parallel --compare-to-serial  $GKW_HOME/tests/standard $GKW_HOME/tests/more

gkwmake clean
gkwmake -j DEBUG=on OPTFLAGS=off CONFIG=config/btppx/default_omp.mk
gkw_run_tests --parallel --compare-to-serial  $GKW_HOME/tests/standard $GKW_HOME/tests/more
gkw_run_tests --serial  $GKW_HOME/tests/standard $GKW_HOME/tests/more

gkwmake clean
gkwmake -j DEBUG=on OPTFLAGS=off CONFIG=config/btppx/without_mpi.mk
gkw_run_tests --serial  $GKW_HOME/tests/standard

gkw_switch_testcase_parameters <<EOF
io_legacy
CONTROL
.false.
y
EOF

rm -rf $GKW_HOME/tests/more
gkw_run_tests --gkw-generate-parallelisations=$GKW_HOME/tests/more

gkwmake clean
gkwmake -j DEBUG=on OPTFLAGS=off
gkw_run_tests --compare-to-serial $GKW_HOME/tests/standard $GKW_HOME/tests/more

gkwmake clean
gkwmake -j DEBUG=on OPTFLAGS=off CONFIG=config/btppx/default_omp.mk
gkw_run_tests --compare-to-serial $GKW_HOME/tests/standard $GKW_HOME/tests/more

gkwmake clean
gkwmake -j DEBUG=on OPTFLAGS=off CONFIG=config/btppx/without_mpi.mk
gkw_run_tests --serial $GKW_HOME/tests/standard