Contributing to Transmog¶

Contributions to Transmog are welcome and appreciated. This guide covers how to set up a development environment and submit changes.

Getting Started¶

Prerequisites¶

Python 3.10 or higher
Git
Poetry (for dependency management)

Installing Poetry¶

Poetry manages project dependencies and virtual environments automatically.

Using pipx (recommended):

# Install pipx (if not already installed)
brew install pipx  # macOS
# For other systems, see: https://pipx.pypa.io/stable/installation/

# Ensure pipx is on your PATH
pipx ensurepath

# Install Poetry via pipx
pipx install poetry

# Optional: Enable shell completions
poetry help completions

Alternative installation methods:

See the Poetry installation guide for other options.

Development Setup¶

Fork and clone the repository

git clone https://github.com/your-username/transmog.git
cd transmog

Run the setup script
```
python3 scripts/setup_dev.py
```
This script will:
- Verify Python version compatibility (3.10+)
- Check for Poetry installation
- Install all dependencies via Poetry
- Set up pre-commit hooks
Verify the setup

poetry run pytest

Making Changes¶

Development Workflow¶

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes

Write code, add tests, update documentation as needed.

Run tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=transmog

# Run specific tests
poetry run pytest tests/unit/test_specific.py

Commit your changes

Pre-commit hooks will automatically format and check code on commit.
```
git add .
git commit -m "Brief description of changes"
```
Push and create a pull request

git push origin feature/your-feature-name

Then open a pull request on GitHub with a description of your changes.

Running Commands¶

All commands should be run through Poetry to use the project’s virtual environment:

# Run tests
poetry run pytest

# Activate Poetry shell (optional - then commands don't need 'poetry run' prefix)
poetry shell

Code Standards¶

Code style is automatically enforced by pre-commit hooks:

Ruff for code formatting and linting
mypy for type checking
interrogate for docstring coverage
bandit for security checks

No manual formatting is required - just commit and the hooks handle the rest.

Codebase Structure¶

The codebase is organized into focused modules:

src/transmog/api.py - Public API (flatten, flatten_stream, FlattenResult)
src/transmog/config.py - Configuration dataclass
src/transmog/flattening.py - Core flattening, metadata, and array extraction logic
src/transmog/iterators.py - Input normalization for JSON and JSONL sources
src/transmog/streaming.py - Streaming pipeline orchestration
src/transmog/writers/ - CSV, Parquet, ORC, and Avro writers (batch and streaming)
src/transmog/exceptions.py - Exception hierarchy
src/transmog/types.py - Shared enums and processing context
tests/ - Unit, integration, and performance test suites
scripts/ - Maintenance utilities (setup, release automation, benchmarks)

Testing¶

Write tests for new functionality
Maintain or improve test coverage
Use descriptive test names

# Run all tests
poetry run pytest

# Run with coverage report
poetry run pytest --cov=transmog --cov-report=html

# Run specific test categories
poetry run pytest tests/unit/
poetry run pytest tests/integration/

Documentation¶

Update docstrings for functions and classes
Add examples to demonstrate usage
Update relevant documentation files in docs/
Keep examples runnable and accurate

Documentation style guidelines:

Use passive voice
Avoid personal pronouns (you, we, our)
No temporal language (previously, new version)
Provide complete, runnable examples

Reporting Issues¶

When reporting bugs, include:

Python version and operating system
Transmog version
Minimal code example that reproduces the issue
Expected vs actual behavior
Full error traceback if applicable

Questions and Support¶

Issues: GitHub issues
Documentation: scottdraper8.github.io/transmog

Thank you for contributing to Transmog!