DEVELOPMENT.md

Development Guide

This document explains how to set up your development environment and workflow for contributing to SimNexus.

Development Environment

Prerequisites

• Python 3.10 or newer
• uv for dependency management
• Git

Setup

1. Clone the repository:

   git clone https://github.com/teaching-repositories/simnexus.git
   cd simnexus

2. Create a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .[dev]

   This will install the package in development mode, making the package editable while working on it.

Development Workflow

Code Style and Quality

SimNexus uses:

• Ruff for linting and formatting
• MyPy for type checking

Run linting:

ruff check .

Run formatting:

ruff format .

Run type checking:

mypy simnexus

Testing

SimNexus uses pytest for testing.

Run tests:

pytest

Run tests with coverage:

pytest --cov=simnexus

Documentation

SimNexus uses MkDocs with the Material theme.

Build documentation:

mkdocs build

Serve documentation locally:

mkdocs serve

Project Structure

simnexus/
├── src/                   # Source directory
│   ├── simnexus/          # Package source code
│   │   ├── core/          # Core simulation logic
│   │   ├── cli/           # Command line interface
│   │   ├── tui/           # Terminal user interface
│   │   ├── web/           # Web interface
│   │   ├── viz/           # Visualization utilities
│   │   ├── utils/         # Helper utilities
│   │   └── config/        # Configuration management
│
├── tests/                 # Test suite
├── docs/                  # Documentation
├── examples/              # Example scripts
├── scripts/               # Build and utility scripts
├── .github/               # GitHub workflows and templates
├── pyproject.toml         # Project configuration
└── mkdocs.yml             # Documentation configuration

Releasing

1. Update version in pyproject.toml
2. Update the changelog
3. Run the release script:

   # Install required dependencies if needed
   pip install build twine
   
   # Test the release (uploads to TestPyPI)
   python scripts/release.py --test
   
   # Make the actual release
   python scripts/release.py

Alternatively, you can still create and push tags manually:

git tag -a v0.x.x -m "Release v0.x.x"
git push origin v0.x.x

Continuous Integration

GitHub Actions workflows automatically run:

• Tests on multiple Python versions
• Linting and type checking
• Documentation building and deployment

See .github/workflows/ for details.