Develop#

1 Quick local setup#

# clone and create a dev environment
git clone https://github.com/umami-hep/atlas-ftag-tools.git
cd atlas-ftag-tools
python -m venv .venv # or: conda create -n ftag python=3.11
source .venv/bin/activate

# install the library *and* dev extras
python -m pip install -e ".[dev]"

# install pre-commit hooks (formatting, linting, typing)
pre-commit install
pre-commit run --all-files

Why use -e? The editable install means you can import ftag from any directory while editing the source in place.

2 Branching & PR policy#

Branch

Purpose

Protection rules

main

always deployable; releases are tagged from here

✓ CI must pass
✓ linear-history

feature/xyz

work in progress, short-lived

none

release/*

back-ports / hot-fixes after a tag

same rules as main

  1. Open a Pull Request early; mark it Draft if it’s not ready.

  2. At least one review from the atlas-ftag-tools dev-team is required.

  3. Squash-merge once green; avoid merge commits.

3 Code style & static checks#

Tool

Checked in CI

Fix command

black

formatting

black .

ruff (pyproject.toml)

lint + simple refactors

ruff check . --fix

mypy

type safety

mypy ftag

isort (via ruff)

import order

auto-fixed by ruff

pre-commit

umbrella runner

pre-commit run --all-files

How the hook chain works#

pre-commit ➜ ruff ➜ black ➜ mypy

If a stage fails the commit is rejected. Run the hook manually to fix issues before pushing:

pre-commit run --all-files

4 Testing strategy#

  • Unit tests live in ftag/tests/ and follow the pytest conventions.

  • CI executes the suite on 3 Python versions (3.9, 3.11, 3.12) and uploads a coverage report.

# local one-liner
pytest ftag/tests/

Coverage must stay ≥ 90 %. If you add logic, add matching tests; if you change public behaviour, update the doc-strings and the examples.

5 Communication channels#

  • GitHub Issues – bug reports & feature requests

  • Mattermost Umami / puma / upp – quick questions, coordination

When in doubt, open an Issue and tag the maintainer team. Happy coding — and may your $b$-tagging be ever accurate! 🎉