Developing the system

Set-up of the development environment is very similar to a production environment, see README.rst for details on how to do this.

The main difference is to use PROJECT_MODE= development (or not include any PROJECT_MODE, development is default), in your local-conf.mk. This will stop CLiC from being started automatically so you can run the server in debug mode. It will also disable NGINX’s server cache so you won’t get stale responses.

To start the API server in debug mode:

make start

To log database queries that the API makes:

QUERY_LOG=yes make start
QUERY_LOG=explain make start  # Also include explain plan

Client-side development

To run tests, lint code and compile:

make -C client

…you will need to do this after any change to the HTML/CSS/JS source.

Server-side development

To run unit tests:

make -C server test

Coverage reports

Coverage reports can be built for both client and server:

make coverage

…the reports will be available through the reports at the end.

Exercise API integration tests

This repository contains some canned API calls and output that can be run against any server. For example:

./exercise.sh http://cal-n-clic-01.bham.ac.uk exercise_outputs/*

Favico regeneration

Upload assets/logo.svg to http://cthedot.de/icongen/, and place the results into `client/www/index.html and client/www/iconx as appropriate.

Preparing a release

Steps for making a release:

VERSION="2.0.0-beta5"
echo -e "## ${VERSION} ($(date +'%Y-%m-%d'))\n" | cat - CHANGELOG.md > CHANGELOG.md.n
mv CHANGELOG.md.n CHANGELOG.md
git commit -m "CHANGELOG: Release ${VERSION}" CHANGELOG.md
git tag -am "Release ${VERSION}" v${VERSION} HEAD
git push && git push --tags

Documentation

readthedocs is used for our documentation. In order for newly released versions of CLiC (as managed by tags, e.g. v2.1.2) to be included in readthedocs please make sure to follow the above instructions in ‘Preparing a release’ when updating CLiC on the production server.

You can access the settings for CLiC’s readthedocs by going to: https://readthedocs.org/projects/clic/

If you have maintainer access you can modify which versions of CLiC are included in the readthedocs, including what the ‘latest’ version is. Tags are pulled through automatically, but branches are not, so these will need to be manually set.

If you need maintainer access, please request from an existing maintainer.

Sphinx will also be run locally for testing, and if it proves useful in future.

To re-build documentation:

make -C docs

To view the documenation built, go to /local-docs/ for your instance.

By default, this only generates the LaTeX needed for the PDF output, which will be available in docs/_build/latex/clic-userguide.tex. To build a PDF from this, you first need to install:

apt install texlive-latex-recommended \
            texlive-fonts-recommended \
            texlive-latex-extra \
            latexmk

…then you can build with:

make -C docs pdf

The pdf will be available at /local-docs/latex/clic-userguide.pdf.