Skip to content

Developing moneyflow

This guide covers the essential development workflow for contributing to moneyflow.

Quick Start

# Clone repository
git clone https://github.com/wesm/moneyflow.git
cd moneyflow

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies (creates .venv)
uv sync

# Run the app in demo mode
uv run moneyflow --demo

# Run tests
uv run pytest -v

# Run type checker
uv run pyright moneyflow/

Development Environment

Required: - Python 3.11+ - uv - Package manager

Optional: - VS Code or PyCharm with Python extension

Development Workflow

Working on Documentation

To preview documentation changes locally with live reload:

# Serve docs with live reload (auto-refreshes on file changes)
uv run mkdocs serve --livereload

# Then open http://127.0.0.1:8000 in your browser
# Edit files in docs/ and see changes instantly

Note: The --livereload flag is important - without it, changes won't auto-refresh in the browser.

Before Starting Work

git pull
uv sync
uv run pytest -v  # Ensure clean starting point

Making Changes

# Make your changes

# Run all code quality checks
uv run pytest -v                          # Tests must pass
uv run pyright moneyflow/                 # Type checking
uv run ruff format --check moneyflow/ tests/  # Code formatting
uv run ruff check moneyflow/ tests/       # Linting

# Auto-fix formatting and linting issues
uv run ruff format moneyflow/ tests/
uv run ruff check --fix moneyflow/ tests/

# Commit (only if all checks pass)
git add -A
git commit -m "your message"

Running Tests

# All tests
uv run pytest -v

# Specific file
uv run pytest tests/test_data_manager.py -v

# Stop on first failure
uv run pytest -x

# With coverage
uv run pytest --cov --cov-report=html
open htmlcov/index.html

CI/CD

Tests run automatically on every push and pull request: - Python 3.11, 3.12 compatibility - Full test suite - Type checking with pyright

See .github/workflows/test.yml for details.

Release Process

# 1. Bump version (runs all quality checks automatically)
./scripts/bump-version.sh 0.x.y

# 2. Review the version bump commit
git show

# 3. Push to GitHub
git push && git push --tags

# 4. Publish to PyPI (if authorized)
./scripts/publish-pypi.sh

The bump-version.sh script automatically: - Runs all tests - Runs type checking (pyright) - Checks code formatting (ruff format) - Runs linter (ruff check) - Updates version in pyproject.toml and mkdocs.yml - Updates uv.lock - Creates commit and git tag

This ensures releases never have failing tests or code quality issues.

Troubleshooting

Tests fail after git pull: 

uv sync  # Sync dependencies

Import errors or stale cache: 

# Clear Python cache
find . -type d -name __pycache__ -exec rm -rf {} +

# Reinstall dependencies
uv sync --reinstall

Module not found errors: 

# Ensure you're using uv run
uv run pytest -v  # Correct
pytest -v         # Wrong - won't find modules

Getting Help