Appendix B — Contributing

Thank you for considering contributing to the Animals In Motion project! We welcome contributions in various forms, including bug reports, requests for content improvement, as well as new tutorials or case studies.

B.1 Setting up the development environment

Begin by cloning the repository and navigating to its root directory:

git clone https://github.com/neuroinformatics-unit/course-animals-in-motion.git
cd course-animals-in-motion

We use conda to manage dependencies. First, create a development environment using the environment-dev.yaml file, and activate it:

conda env create -n animals-in-motion-dev -f environment-dev.yaml
conda activate animals-in-motion-dev

To enable the pre-commit hooks, run the following command once:

pre-commit install

This is a Quarto book project, with its source code located in the book/ directory. We refer you to the Quarto documentation for more information on how books are structured and configured.

To render/preview the book locally, you’ll need the Quarto CLI installed, as well as the VSCode Quarto extension

You will also need to make sure that the QUARTO_PYTHON environment variable is set to the path of the python executable in the development conda environment. This guarantees that the Quarto CLI will use the correct Python interpreter when rendering the book.

export QUARTO_PYTHON=$(which python)

Then, you can render the book using:

quarto render book

Code cells in .qmd files execute automatically on render. Their results are cached (execute: cache: true in book/_quarto.yml), so on subsequent renders only cells you’ve modified are re-run. If you need to force a full re-execution—e.g. after changing data or an imported dependency that Quarto cannot detect—refresh the cache:

quarto render book --cache-refresh

You can view the rendered book by opening the book/_book/index.html file in your browser.

Alternatively, use quarto preview for live-reloading during development—the book rebuilds and refreshes in the browser automatically as you save changes:

quarto preview book

Note that quarto preview still executes code cells and uses the cache, so the first preview after a change may take a moment.

Some chapters (e.g. 04-movement-intro.qmd, 05-movement-mouse.qmd, 07-boris-tutorial.qmd) execute code cells that read the CalMS21 dataset from ~/.movement/CalMS21/. movement’s own sample datasets are fetched automatically, but CalMS21 needs to be manually downloaded from Dropbox and placed at that path (see prerequisites Section A.4 for the link and folder structure), otherwise rendering those chapters will fail with a missing-file error.

B.2 Authoring content

Book chapters are written primarily as Quarto Markdown files (.qmd). These can contain a mix of narrative and interactive content, such as code exercises. See Quarto computations > Using Python to learn more about executable code blocks.

We recommend using the Quarto VSCode extension for authoring and previewing content.

The chapter source files reside in the book/ directory and have to be linked in the book/_quarto.yml file for them to show up. See Book Crossrefs on how to reference other chapters.

Visual styling (colours, fonts, logo) is centralised in book/_brand.yml, applied via the brand theme layer specified under format.html.theme in book/_quarto.yml. To change the book’s appearance, update book/_brand.yml.

Bibliographical references should be added to the book/references.bib file in BibTeX format. See Quarto authoring > Citations for more information.

In general, cross-referencing objects (e.g. figures, tables, chapters, equations, citations, etc.) should be done using the @ref syntax, e.g. See @fig-overview for more details.

B.2.1 Adding exercises and their solutions

Exercises and their solutions are authored inline in the chapter source, but at render time each solution is moved into a per-chapter “Solutions” section by the book/collect-solutions.lua filter (registered in book/_quarto.yml).

Write each exercise prompt as an .exercise-prompt div:

::: {.exercise-prompt}
Describe the task here.
:::

Immediately after it, write the solution as an .exercise-solution div:

::: {.exercise-solution}
Write your solution here (prose and `{python}` code cells).
:::

Each .exercise-prompt must be followed by exactly one .exercise-solution, in order. As long as this contract is respected, the filter will automatically number and style the exercises and solutions, and move the solutions to the end of the chapter (with back-links to the corresponding exercise).

Solution code cells execute in the chapter’s kernel (before the filter runs), so they can use variables and imports defined earlier in the chapter.

B.3 Pre-commit hooks

We use pre-commit to run checks on the codebase before committing.

Current hooks include:

  • codespell for catching common spelling mistakes.
  • markdownlint for (Quarto) Markdown linting and formatting.
  • ruff for code linting and formatting.

These will prevent code from being committed if any of these hooks fail. To run all the hooks before committing:

pre-commit run  # for staged files
pre-commit run -a  # for all files in the repository

B.4 Versioning and releasing

We use Calendar Versioning (CalVer) and specifically the YYYY.0M scheme (e.g. 2025.08 for August 2025).

To create a new release, first update the book/index.qmd file. Specifically, add a row like the following to the “Versions” table:

| `v2026.08` | version used for the OSSS in August 2026 |

You also need to create a new tag in the vYYYY.MM format (e.g. v2025.08) and push it to the repository. Don’t forget the v prefix for the tag name!

For example:

git tag v2026.08
git push origin --tags

B.5 Continuous integration (CI)

The CI workflow is defined in the .github/workflows/build_and_deploy.yaml file and can be triggered by:

  • Pushes to the main branch
  • Pull requests
  • Releases, i.e. tags starting with v (e.g., v2026.08)
  • Manual dispatches

The workflow is built using GitHub actions and includes three jobs:

  • linting: running the pre-commit hooks;
  • build: rendering the Quarto book and uploading the rendered artifact;
  • deploy: deploying the book artifact(s) to the gh-pages branch (only for pushes to the main branch and releases).

Each release version is deployed to a folder in the gh-pages branch, with the same name as the release tag (e.g., v2026.08).

There’s also a special folder called dev that is deployed for pushes to the main branch.

Versions up to and including v2025.10 were additionally deployed to a vYYYY.MM-answers folder (separate builds for with and without solutions). Those folders remain online as historical archives; new versions no longer produce them.