Skip to content

Getting Started

Prerequisites

  • Python 3.12+
  • uv package manager
  • Git
  • GitLab CLI (glab) — for issue and MR management

Clone and Set Up

See Installation Guide → For Developers for cloning the repository, running uv sync --all-groups, and verifying the CLI with uv run fnb --help.

task env:setup does the equivalent (dependency sync + pre-commit hook installation) in one step.

For contributor work, do this inside a dedicated git worktree rather than the main checkout — see below.

Working in an Isolated Branch (git worktree)

This project keeps main clean by developing each branch in its own git worktree rather than switching branches in place:

git worktree add ../worktrees/<feature-branch-name> -b <feature-branch-name>
cd ../worktrees/<feature-branch-name>

uv sync --all-groups

# ... make your changes ...

# Clean up once the branch is merged
cd ../../fnb
git worktree remove ../worktrees/<feature-branch-name>
git branch -d <feature-branch-name>

Running Tests

task test:unit          # fast unit tests only
task test:integration   # integration tests only
task test                # everything, with coverage

# A single test file or test
uv run pytest tests/unit/test_cli.py
uv run pytest tests/unit/test_cli.py::test_version_command

task test:ci simulates the full CI pipeline locally: unit tests, format check, and pre-commit hooks — run this before opening a merge request.

Building the Documentation

task docs:serve         # serve locally with live reload at http://localhost:8000
task docs:build         # build static HTML into site/
task docs:build:clean   # clean rebuild; watch the output for "page does not exist" warnings

Next Steps

  • Coding Standards for style, typing, and test conventions
  • Workflow for how issues, branches, and merge requests fit together