Bootstrap local .venv in make targets and quickstart docs

CONTRIBUTING.md

@@ -7,6 +7,8 @@ make install-dev
 make demo-migrate
 ```
 
+`make install-dev` creates `.venv` automatically and installs project dev dependencies into it.
+
 If you want local overrides:
 
 ```bash

Makefile

@@ -7,28 +7,36 @@ API_SERVICE ?= productory-demo
 DB_SERVICE ?= productory-db
 SERVICE ?= $(API_SERVICE)
 TEST ?=
+VENV ?= .venv
+VENV_PY := $(VENV)/bin/python3
 
 DC := $(COMPOSE) --env-file $(ENV_FILE) -f $(COMPOSE_FILE)
 
 .DEFAULT_GOAL := help
 
-.PHONY: help install-dev qa coverage demo-migrate demo-run demo-stop demo-logs demo-check up down restart logs ps migrations superuser drop-create-db loaddata show-urls test test-quick test-one test-all shell ipython
+.PHONY: help venv install-dev qa coverage demo-migrate demo-run demo-stop demo-logs demo-check up down restart logs ps migrations superuser drop-create-db loaddata show-urls test test-quick test-one test-all shell ipython
 
 help: ## Show available commands
 	@grep -E '^[a-zA-Z_-]+:.*##' Makefile | sort | awk 'BEGIN {FS = ":.*## "}; {printf "%-18s %s\n", $$1, $$2}'
 
-install-dev: ## Install package + dev dependencies locally
-	python3 -m pip install -e '.[dev]'
+venv: ## Create local virtualenv at .venv (if missing)
+	@if [ ! -x "$(VENV_PY)" ]; then \
+		python3 -m venv $(VENV); \
+		$(VENV_PY) -m pip install --upgrade pip; \
+	fi
+
+install-dev: venv ## Install package + dev dependencies into local .venv
+	$(VENV_PY) -m pip install -e '.[dev]'
 
-qa: ## Run lint, format check, type check, and tests
-	python3 -m ruff check src tests demo
-	python3 -m ruff format --check src tests demo --exclude '*/migrations/*'
-	python3 -m mypy src
-	python3 -m pytest tests
+qa: venv ## Run lint, format check, type check, and tests
+	$(VENV_PY) -m ruff check src tests demo
+	$(VENV_PY) -m ruff format --check src tests demo --exclude '*/migrations/*'
+	$(VENV_PY) -m mypy src
+	$(VENV_PY) -m pytest tests
 
-coverage: ## Run tests with coverage report
-	python3 -m coverage run -m pytest tests
-	python3 -m coverage report
+coverage: venv ## Run tests with coverage report
+	$(VENV_PY) -m coverage run -m pytest tests
+	$(VENV_PY) -m coverage report
 
 demo-migrate: ## Run migrations for the demo project
 	$(DC) up -d $(DB_SERVICE) $(API_SERVICE)
@@ -47,8 +55,8 @@ demo-stop: ## Stop detached demo docker stack
 demo-logs: ## Tail demo container logs
 	$(DC) logs -f --tail=200 $(API_SERVICE)
 
-demo-check: ## Run Django checks for demo project
-	python3 demo/manage.py check
+demo-check: venv ## Run Django checks for demo project
+	$(VENV_PY) demo/manage.py check
 
 up: ## Start and build docker services
 	$(DC) up -d --build

README.md

@@ -28,6 +28,8 @@ make install-dev
 make demo-run
 ```
 
+`make install-dev` bootstraps a local `.venv` and installs dev dependencies into it.
+
 Then:
 
 - Catalog products API: `http://127.0.0.1:8010/api/catalog/products/`

docs/quickstart.md

@@ -9,6 +9,8 @@ make install-dev
 make demo-run
 ```
 
+`make install-dev` creates a local virtual environment at `.venv` (if missing) and installs dev dependencies there.
+
 `make demo-run` runs the demo stack in detached Docker mode and applies migrations.
 It seeds 10 categories, 10 collections, 50 products, stock, 6 bundles, and 5 month-end promotions.
 It also seeds 10 addresses, 32 varied carts, and 18 varied orders for dashboard demos.