Contributor Quickstart

Set up Bengal for development and start contributing

2 min read 475 words

Set up Bengal for development and start contributing.

Prerequisites

Development Setup

0/4 complete
  • Python 3.14+ (3.14t recommended for best performance)
  • Git installed and configured
  • A GitHub account
  • Code editor (VS Code, PyCharm, etc.)

Clone and Install

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Fork the repo on GitHub first, then:
git clone https://github.com/YOUR-USERNAME/bengal.git
cd bengal

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Verify installation
bengal --version

Run Tests

1
2
3
4
5
6
7
8
# Run all tests
pytest

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

# Run with coverage
pytest --cov=bengal

Project Structure

bengal/
├── bengal/
│   ├── core/           # Passive data models (no I/O)
│   ├── orchestration/  # Build coordination
│   ├── rendering/      # Templates and content
│   ├── discovery/      # Content/asset discovery
│   ├── cache/          # Caching infrastructure
│   ├── health/         # Validation and checks
│   └── cli/            # Command-line interface
├── tests/
│   ├── unit/           # Fast, isolated tests
│   ├── integration/    # Multi-component tests
│   └── roots/          # Test fixtures
└── 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.

  3. 3

    Add Tests

    10-30 min

    All changes need tests - unit tests for isolated logic, integration tests for workflows.

    Add tests intests/unit/ortests/integration/.

  4. 4

    Run Linters

    1 min

    Format and lint your code before committing.

    1
2
3
4
5
    # Format code
ruff format bengal/ tests/

# Lint
ruff check bengal/ tests/ --fix
  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 the project's CONTRIBUTING guidelines.

  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

1
2
cd site
bengal serve

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

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

Next Steps