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.

Branching and publishing to live

The CLiC project has several long-lived branches:

development

The default branch, the test server will run this version of the CLiC code. Documentation updates should be done directly in this branch. Code updates should be done in a feature branch and merged with a pull request.

2.x (e.g. 2.0, 2.1, …)

Production branch for major versions of CLiC, the production server will be running one of these branches. Generally, new releases should be done with a pull request from the development branch. Any bug-fix changes should be done with a pull request directly to the 2.x branch.

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.