Commit 539992f

practices/development_guide

Development Guide Files

What is it? Why do it?

Development guide files are markdown files that can be used by both humans and AI agents to provide guidance on development practices within a project. They can explain high level design decisions, help ensure consistency, and describe the best practices used throughout the project. When used in combination with AI agents, these files can both optimize the development workflow (by providing overviews) and assist in maintaining high code quality standards.

Developers should extend this file and add information as the project progresses to capture the current state of both the code and the best practices.

Common Sections

We recommend including sections on the following topics:

- Overview of the project, including how it is structured, its main components, and how it will be used.

- Design "North Stars" (key guiding principles for the project's development)

- How to set up the development environment

- How to run tests and linting (common commands)

- Repository structure (especially for projects with subdirectories)

- Coding standards and style guidelines

- Project specific considerations such as default units.

Default Information

The default DEVELOPMENT_GUIDE.md file is generated with recommendations and principles corresponding to the Python Project Template.

For example, the default "North Stars" provided are:

- Correctness is the Top Priority.

- Code should be modular and use a few consistent APIs.

- Make Easy Things Easy, Hard Things Possible.

- Code should follow a standard format.

- Code should be documented.

Developers should edit any of the information in the DEVELOPMENT_GUIDE.md file to reflect their design goals and philosophy.

# Agent Instructions

Read [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md) before making any changes. It is the canonical reference and may include information on design principles, core abstractions, API conventions, development workflow, and best-practices.

# {{project_name}} Development Guide

This document provides a guide for contributing to the development of this project, and can include information such as design principles, core abstractions, API conventions, development workflow, and best-practices.

## Design Goals and North Stars

**CRITICAL: Always keep these design principles in mind when making changes to the project.**

**Correctness is the Top Priority.** The code should include thorough tests. Any approximations should be clearly documented and communicated to the user.

**Code should be modular and use a few consistent APIs.**

**Make Easy Things Easy, Hard Things Possible.** Common use cases should require minimal configuration or set up, but users should also be able to perform complex work.

**Code should follow a standard format** with automatic formatting supported by `ruff`.

**Code should be documented.** Docstrings should provide sufficient API information, such as parameter explanations, for users to understand the code.

## Common Commands

```bash

# All tests

python -m pytest

# Parallel tests

python -m pytest -n auto

# Lint and format (let the linter fix style — do not hand-tune)

{% if 'ruff_lint' in enforce_style or 'ruff_format' in enforce_style -%}

ruff check src/ tests/

ruff format src/ tests/

{% endif -%}

{% if 'black' in enforce_style -%}

black src/

black test/

{% endif -%}

# Pre-commit (runs ruff lint/format, workflow/pyproject schema checks, pytest, etc.)

pre-commit run --all-files

{% if include_docs -%}

# Build docs

sphinx-build -M html ./docs ./_readthedocs

{% endif -%}

```

## Repository Structure

```

src/{{package_name}}/ Main package

tests/{{package_name}}/ Test suite

{% if include_docs -%}

docs/ Sphinx documentation sources

{% endif -%}

{% if include_benchmarks -%}

benchmarks/ ASV performance benchmarks

{% endif -%}

```

## Testing Conventions

- **File naming:** `tests/{{package_name}}/<SUBDIR>/test_<name>.py`, mirroring the `src/{{package_name}}/` layout.

- **Fixtures:** defined in `tests/conftest.py`. Use existing fixtures, do not duplicate test data.

- Default test run: `python -m pytest`