Skip to content

🛠️ Development Guide (Hatch-based)

This guide covers how to set up a local development environment, run tests, and manage code quality for Azure Functions Doctor, using Hatch and a Makefile for workflow automation.

📦 Prerequisites

  • Python 3.9+ installed on your system
  • Git for version control
  • Hatch as the build and environment manager (installed via pip install hatch)
  • Make (for running the provided Makefile targets)
  • (Optional) uv for fast dependency installation (pip install uv)

🛠️ Project Structure Overview

azure-functions-doctor-for-python/
├── Makefile
├── pyproject.toml
├── hatch.toml
├── src/
│   └── azure_functions_doctor/
│       ├── __init__.py
│       ├── cli.py
│       ├── doctor.py
│       ├── handlers.py
│       ├── utils.py
│       ├── assets/
│       │   └── rules.json
│       └── checks/
├── tests/
│   ├── test_cli.py
│   ├── test_handler.py
│   └── test_*.py
├── docs/
│   ├── index.md
│   ├── usage.md
│   ├── rules.md
│   ├── diagnostics.md
│   └── development.md
├── examples/
│   └── basic-hello/
│       └── diagnose-output.md
└── ...
  • Makefile: Defines common commands for creating the environment, running tests, linting, formatting, and publishing.
  • pyproject.toml and hatch.toml: Configuration for Hatch environments and project metadata.
  • src/azure_functions_doctor/: Core application code, including CLI entrypoint, diagnostic logic, and rule assets.
  • tests/: Unit and integration tests for the project.
  • docs/: Documentation files used by MkDocs (if enabled) or GitHub pages.
  • examples/: Contains sample Azure Functions projects and expected outputs.

🚀 Initial Setup

  1. Clone the repository: bash git clone https://github.com/yeongseon/azure-functions-doctor-for-python.git cd azure-functions-doctor-for-python

  2. Create and activate a virtual environment using the Makefile: bash make venv source .venv/bin/activate # On Windows (PowerShell): .venv\Scripts\Activate.ps1

  3. Install project dependencies via Hatch (or using uv if preferred): bash make install # or, if using uv: uv install

  4. Install pre-commit hooks for code formatting and linting: bash make precommit-install

Note: The Makefile ensures Hatch commands run inside the appropriate environment. If you bypass Makefile, you can manually do: bash hatch env create default hatch run pip install -r requirements-dev.txt hatch run pre-commit install

🧪 Running Tests and Quality Checks

1. Format Code

Use Black and Ruff via Makefile to enforce consistent styling:

make format

2. Lint Code

Run Ruff and Mypy for linting and type checks:

make lint

3. Type Checking

Perform static type analysis with Mypy:

make typecheck

4. Run Unit Tests

Execute all tests using pytest:

make test

5. Combined Quality Checks

Run formatting, linting, type checking, and tests in one command:

make check

6. Generate Coverage Report

Produce a coverage report (HTML + XML):

make cov
  • Opens htmlcov/index.html for browser viewing
  • Generates coverage.xml for CI integrations (e.g., Codecov)

🎯 Development Workflow

  1. Create a feature branch: bash git checkout -b feature/your-description

  2. Implement changes in src/azure_functions_doctor/ and/or update rules.json under src/azure_functions_doctor/assets/.

  3. Add new tests in the tests/ directory to cover your changes.

  4. Run quality checks locally: bash make check

  5. Commit changes with Conventional Commits format: git commit -m "feat: add new check for custom config file"

  6. Push and open a Pull Request to main.

📝 Makefile Targets Reference

Target Description
make venv Create a Python virtual environment at .venv/
make install Install runtime and dev dependencies via Hatch (hatch install)
make precommit-install Install pre-commit hooks (Black, Ruff, etc.)
make format Format code with Black and apply Ruff fixes
make lint Run Ruff and Mypy checks
make typecheck Perform static type checking with Mypy
make test Run pytest
make check Run formatting, linting, typechecking, and tests in sequence
make cov Generate coverage report and open HTML index
make docs Serve MkDocs locally (if MkDocs configured)
make release-patch Bump patch version, update changelog
make release-minor Bump minor version, update changelog
make release-major Bump major version, update changelog
make publish Publish package to PyPI (requires credentials in environment)

For detailed release workflow, refer to release_process.md.

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository and create a new branch.
  2. Follow the Development Workflow above.
  3. Ensure tests pass and code quality checks succeed.
  4. Submit a Pull Request with a clear description of your changes.

Thank you for helping improve Azure Functions Doctor!

📄 License

This project is licensed under the MIT License.