Development Setup

🚀Development Setup

Python 3.14+

Create an isolated editable Reflow environment with tests, formatting, linting, packaging, and Git-hook tools.

Commandpython -m pip install -e ".[dev]"

📦Category

Developer Guide

🚀Quick Command

create venv -> install dev tools -> enable hooks

---

editable installpytestRuffBlackpre-commit

---

🐍

Required Python

3.14 or newer

📦

Install Mode

Editable

📁

Environment

venv recommended

🚀

Optional Runtime Tools

Docker and GitHub CLI

Goal

Use an environment whose reflow executable resolves to the active source checkout. The dev dependency group is required for pytest, coverage, Ruff, Black, pre-commit, packaging, and other contributor commands.

---

Requirements

📌Requirements

Python 3.14+

Required

Reflow's package metadata and quality-tool targets require Python 3.14 or newer.

Git

Required

Repository and tag workflows require Git, while tests use isolated or mocked boundaries.

pip and venv

Required

Install into an isolated environment instead of the system interpreter.

GNU Make

Optional

Use the modular Make targets for repeatable setup and validation.

Docker

Optional

Required only for container and Compose validation.

GitHub CLI

Optional

Required only for live GitHub release discovery; ordinary tests mock this boundary.

---

Manual Setup

Create and install

bash

python -m venv venv

# Windows PowerShell

venv\Scripts\Activate.ps1

# Linux or macOS

# source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Use python -m pip install -e ".[dev,docs]" only when you also need the repository's MkDocs toolchain.

---

Makefile Setup

The Make workflow expects the conventional venv/ directory and invokes its Python interpreter directly.

Setup helpers

bash

make venv
make upgrade-pip
make install-dev

# Combined environment setup and Git-hook installation

make setup

Run make help-local to inspect the complete local command groups.

---

Pre-Commit Workflow

Reflow's hook configuration applies Ruff safe fixes, Black formatting, trailing-whitespace cleanup, and final-newline correction. Ruff and Black use the policies in pyproject.toml.

Install and run hooks

bash

# Install the Git hook and isolated hook environments
make pre-commit-install-hooks

# Validate .pre-commit-config.yaml

make pre-commit-validate

# Check files currently staged for commit

make pre-commit-run-staged

# Check every tracked repository file

make pre-commit-run

⚠️Refresh is an intentional maintainer action

make pre-commit-refresh updates hook revisions, clears cached hook environments, reinstalls them, and runs every hook against all files. It may require network access and can modify .pre-commit-config.yaml and active source files. Review the complete diff before keeping its output.

---

Verify the Environment

📌Before You Begin

• Python is supportedRequired

  python --version reports Python 3.14 or newer.

• Editable Reflow resolvesRequired

  reflow --help and python -m app --help load from the selected environment.

• Quality tools resolveRequired

  pytest, Ruff, Black, and pre-commit run through python -m.

• No live credentials are requiredRequired

  Ordinary development tests use mocks and temporary repositories.

Environment check

bash

python --version
python -m pip show git-reflow
reflow --help
python -m app --help
python -m pytest --version
python -m ruff --version
python -m black --version
python -m pre_commit --version

---

🚀Related Commands

Commands commonly used together with this command.

Testing

Run focused and complete Reflow validation.

Contributing

Follow Reflow's safety and review workflow.

Getting Started

Compare contributor setup with the end-user workflow.

Dockerize

Review the supported container workflow.