Developing the system¶

Set-up of the development environment is very similar to a production environment, see https://github.com/mahlberg-lab/clic/blob/HEAD/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 ./client/www/logos/clic_icon.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/

On this page, there should be a line for each CLiC branch / major.minor version, and ‘latest’. When a new branch is started in CLiC the corresponding branch needs to be added to readthedocs, otherwise there will be a 404 error when selecting the “help” link. If a new branch is missing, go to the above page and…

# “Add version” # Search for the branch number in the box # Turn on “Active” # Click “Update version”

You should also change the default branch by…

# “Settings” in top-right corner # Select new default branch in drop-down

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.

FlexiConc: Upgrading & dependencies¶

FlexiConc is run client-side within a pyodide environment.

To upgrade the version used, or to add dependencies for a package, see flexiclic/Makefile.