Contributor Quickstart

Set up Bengal for development and start contributing

3 min read 686 words

Set up Bengal for development and start contributing.

Prerequisites

Development Setup

0/4 complete
  • Python 3.14 or later (3.14t recommended for parallel builds)
  • Git installed and configured
  • A GitHub account
  • Code editor (VS Code, PyCharm, or similar)

Clone and Install

# Fork the repo on GitHub first, then:
git clone https://github.com/YOUR-USERNAME/bengal.git
cd bengal

# Create virtual environment (Python 3.14t recommended)
make setup

# Install dependencies (PEP 735 dependency groups) into .venv
make install

# Verify installation
uv run bengal --version

Run Tests

# Run all tests
make test

# Run specific test file
uv run pytest tests/unit/test_page.py

# Run with coverage
uv run pytest --cov=bengal

# Run tests in parallel
uv run pytest -n auto

Project Structure

bengal/
├── bengal/
│   ├── core/           # Passive data models (no I/O)
│   ├── orchestration/  # Build coordination
│   ├── rendering/      # Templates and content rendering
│   ├── parsing/        # Markdown parsing and AST helpers
│   ├── content/        # Content discovery + remote sources
│   ├── cache/          # Caching infrastructure
│   ├── health/         # Validation and health checks
│   ├── config/         # Configuration loading
│   ├── server/         # Dev server with live reload
│   └── cli/            # Command-line interface
├── tests/
│   ├── unit/           # Fast, isolated tests
│   ├── integration/    # Multi-component tests
│   └── roots/          # Test fixtures (sample sites)
├── benchmarks/         # Performance benchmarks
└── site/               # Documentation site

Development Workflow

  1. 1

    Create a Branch

    1 min

    Start with a descriptive branch name for your feature or fix.

    git checkout -b feature/my-feature
  2. 2

    Make Changes

    varies

    Edit code in the appropriate module following existing patterns.

    Edit code inbengal/, following existing patterns. Core modules are passive data structures. Operations go in orchestrators.

  3. 3

    Add Tests

    10-30 min

    All changes need tests. Unit tests for isolated logic, integration tests for workflows.

    Add tests intests/unit/ or tests/integration/.

  4. 4

    Run Linters

    1 min

    Format and lint your code before committing.

    # Format code
uv run ruff format bengal/ tests/

# Lint and auto-fix
uv run ruff check bengal/ tests/ --fix

# Type check
uv run ty check bengal/
  5. 5

    Commit

    2 min

    Use descriptive atomic commits that read like a changelog.

    git add -A && git commit -m "core: add feature description"

    Follow the commit message format described in CONTRIBUTING.md.

  6. 6

    Push and Create PR

    5 min

    Push your branch and create a pull request for review.

    git push origin feature/my-feature

    Then create a Pull Request on GitHub.

Build the Docs Site

From the repository root:

cd site
uv run bengal serve

Visit http://localhost:5173 to preview documentation changes.

Tip

To usebengal directly without uv run, activate the virtual environment first: source .venv/bin/activate

Key Principles

  • Core modules are passive — No I/O, no logging inbengal/core/
  • Orchestration coordinates — Build logic lives inbengal/orchestration/
  • Tests are essential — All changes need tests
  • Type hints required — Use Python type hints everywhere
  • Docstrings required — All public functions need Google-style docstrings

CLI Overview

Bengal provides a comprehensive CLI with aliases for common operations:

Command Alias Description
bengal build bengal b Build the site
bengal serve bengal s Start dev server
bengal clean bengal c Clean output directory
bengal validate bengal v Validate site configuration
bengal new site — Create a new site
bengal new page — Create a new page
bengal explain — Introspect a page

Next Steps

  • Architecture — Understand Bengal's internals
  • Testing Patterns — Test best practices
  • About Bengal — Philosophy, benchmarks, and FAQ
  • CONTRIBUTING.md — Full contribution guidelines (in repo root)