Guide for Developers (Jupyter & Git)

Guide for Developers (Jupyter & Git)#

Welcome! If you are contributing Python/R code, spatial analyses, or interactive maps, you will be working directly with Jupyter Notebooks (.ipynb) and Git.

The HaCLAthon relies on the FAIR principles and reproducibility. This guide outlines our technical setup and contribution workflow.

1. The Core Workflow#

Because we use an automated Continuous Integration (CI) pipeline to build this book, we ask developers to follow a standard “Fork & Pull” workflow:

  1. Fork the HaCLAthon GitHub Repository.

  2. Clone your fork locally or open it in a cloud environment.

  3. Create a branch for your feature (e.g., feat/urban-heat-map).

  4. Develop your .ipynb notebook in the notebooks/ directory.

  5. Commit and Push your changes to your fork.

  6. Open a Pull Request against our main branch.

2. Setting up your Computing Environment#

To avoid dependency conflicts, we highly recommend using one of our standardized environments.

Option A: Cloud Execution (Jupyter4NFDI)#

You can run this repository interactively in your browser via the Jupyter4NFDI Hub.

  • Click the 🚀 icon in the top menu bar of this book and select “Binder”.

  • Authenticate using the Helmholtz AAI (IOER members can use “TU Dresden”).

  • The environment will load with all base dependencies pre-installed.

Option B: Local Execution (Carto-Lab Docker)#

For full local reproducibility, we use the IOER FDZ Carto-Lab Docker. This contains a Linux base, JupyterLab, and all major cartographic Python packages.

git clone https://gitlab.vgiscience.de/lbsn/tools/jupyterlab.git
cd jupyterlab
cp .env.example .env
# Edit .env to set the TAG to our current version
docker network create lbsn-network
docker compose pull && docker compose up -d

3. Important: The Jupytext Sync#

This repository uses Jupytext to maintain a bidirectional sync between .ipynb files and .md files.

  • Never edit the .md version of your notebook manually.

  • Write your code in the .ipynb file.

  • Before committing, ensure Jupytext has synced your notebook. Our CI pipeline enforces consistency; if the .md and .ipynb files are out of sync, the build will fail.

4. Commit Message Conventions#

Our Continuous Integration automatically builds versions and changelogs based on commit messages. Please use the Conventional Commits Specification:

  • feat: added interactive folium map to chapter 3 (Creates a minor release)

  • fix: resolved legend overlay issue in heat map (Creates a patch release)

  • docs: fixed typo in API instructions (No version bump)

5. Cross-References and Citations#

  • Literature: Add your references to the references.bib file. Cite them in your notebook using {cite:t} or {cite:p}.

  • Anchors: Do not rely on header names for linking. Define explicit targets above your headers (my-anchor)= and link to them using [Link Text](my-anchor).

Style guidelines and system design.

You can read the full info on our system design, including contribution guidelines and formatting style conventions that we try to adhere, in our Developers section.

Contents