Contributing

General guidelines

The Brokenspoke-analyzer project follows the BNA Mechanics Contributing Guidelines. Refer to them for general principles.

In the sections below we provide instructions for how to set up a developer environment locally or using a development container. Specific instructions will be described in other sections on this page.

Developer environment

Requirements

Setup

Fork brokenspoke-analyzer into your account. Clone your fork for local development:

git clone git@github.com:your_username/brokenspoke-analyzer.git

Then cd into brokenspoke-analyzer, and to setup the project and install dependencies, run:

uv sync --all-extras --dev

Database

The brokenspoke-analyzer requires a PosgreSQL/PostGIS server to run the analysis.

We provide 2 options to make it easy for the developpers to set it up:

  • a Docker compose file which spins up the server with all the required extensions

  • a configure sub-command which helps configuring the server

Serving the documentation site

To render the site when adding new content, run the following command:

just docs-autobuild

Then open the http://127.0.0.1:1111 URL to view the site.

The content will automatically be refreshed when a file is saved on disk.

Administration tasks

Administration tasks are being provided as convenience in a justfile.

More information about Just can be found in their repository. The installation section of their documentation will guide you through the setup process.

Run just -l to see the list of provided tasks.

Running the BNA using Brokenspoke-analyzer

To run using the virtual environment, prefix all your commands with:

uv run

See the command reference manual for more details.

The brokenspoke-analyzer can be run using the bna script defined in pyproject.toml or by activating the virtual environment that was created by uv inside the project and running the cli commands. To run the modified BNA for a city in the US, for example Flagstaff, AZ, using the bna script:

uv run bna --help

For example to run an analysis for Santa Rosa, NM:

uv run bna run usa "santa rosa" "new mexico" 3570670

Development Container

This method provides a replicable developer and debugging environment based on a VS Code development container.

Build and open the application in a development container in VS Code by running the command Dev Containers: Rebuild and Reopen in Container via the command palette (⇧⌘P in Mac or Ctrl+Shift+P in Windows). The database will be started in the background and once the development container opens, a terminal will be available to run the analyzer.

In the development container’s terminal, configure the database:

bna -vv configure custom 4 4096 postgres

Run the analysis:

bna -vv run "united states" "santa rosa" "new mexico" 3570670

After the analysis runs, by default, the results will be exported locally.

All the administration tasks can also be ran inside the development container.

Close the container and return to your local environment by running the command Dev Containers: Reopen Folder Locally via the command palette (⇧⌘P in Mac or Ctrl+Shift+P in Windows). The container running the database will be stopped.

Debugging

You can make changes to the source code of brokenspoke-analyzer and run the debugger to see the effect of your changes. But since the brokenspoke-analyzer package is already installed in the dev container, running the system python interpreter in /usr/local/bin/python/ will run the brokenspoke-analyzer installed in usr/local/lib/python3.13/site-packages. What we need to do is run the debugger using the source brokenspoke-analyzer in /usr/src/app so we create a virtual environment:

uv sync

Then we open the the command palette (⇧⌘P in Mac or Ctrl+Shift+P in Windows) and choose Python: Select Interpreter, ./.venv/bin/python. Once we are set up, we can place breakpoints, and the debugger will pause at breakpoints.