Developers’ Instructions

Git workflow

1. Setup your SSH keys (https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh)

2. Obtain a local copy of the suite:

   git@github.com:MetOffice/inline_model_metrics.git
   

3. Change directory into the repository:

   cd inline_model_metrics
   

4. If you have previously cloned the repository then update your local copy to the latest version:

   git checkout main
   git pull origin main
   

5. Create a branch for your changes and change to this branch:

   git fetch origin
   git branch <branch-name> origin/main
   git checkout <branch-name>
   

6. When you’re happy with your changes, check the changes that you’ve made:

   git status
   git diff
   

7. You can then commit these changes and push them back up to GitHub:

   git commit -am '<commit message>'
   git push origin <branch-name>
   

8. You can make as many commits and pushes as you want.

9. Create a pull request at https://github.com/MetOffice/inline_model_metrics/compare by in the compare box selecting your branch and clicking on “Create pull request”.

10. Once the code has been reviewed then the pull request can be merged using the GitHub web page for that pull request.

11. After merging, change your local copy of the code back to the main branch, delete your local copy of the development branch and pull in the changes from GitHub’s main branch to your local copy:

    git checkout main
    git branch -D  <branch-name>
    git pull origin main
    

To examine complex changes, you might also want to consider using graphical diff rather than just the command line, in which case you should add the following lines to your ~/.gitconfig file:

[diff]
     tool = tkdiff
[difftool]
     prompt = False

and then, rather than just git diff, you can use:

git difftool

Running the tests

1. Load a Python environment in the usual way for your location.

2. Point to the Afterburner installation on your local machine and add this to your PYTHONPATH:

   export AFTERBURNER_HOME_DIR=/path/to/afterburner/software/turbofan/current
   export PYTHONPATH=$AFTERBURNER_HOME_DIR/lib/python:$PYTHONPATH
   

3. Download a local copy of tempest_helper (https://github.com/MetOffice/tempest_helper/) and add it to your PYTHONPATH:

   export PYTHONPATH=/path/to/tempest_helper:$PYTHONPATH
   

4. Add the inline_model_metrics code to your PYTHONPATH:

   export PYTHONPATH=/path/to/inline_model_metrics:$PYTHONPATH
   

5. Run the tests:

   pytest -vv
   

Building the Documentation

In the checked out repository, make sure that your Python environment includes Sphinx (standard scientific ones do):

export PYTHONPATH=/path/to/inline_model_metrics
cd docs
make clean && make html

The build documentation can then be viewed in your browser (replace Firefox with the name of your browser if required):

firefox build/html/index.html

To add new track types

1. Add an option for the new track type to the values in [common=track_type] in rose-meta.conf.

2. Select the new track type in the track_type setting in the [common] section of rose-app.conf.

3. Add [<track_type>_detect] and [<track_type>_stitch] sections to rose-app.conf.