Skip to content

Contributing to Rugo

Thank you for your interest in contributing to Rugo! This guide will help you get started.

Getting Started

Prerequisites

  • Python 3.9 or newer
  • C++17 compatible compiler
  • Git

Development Setup

  1. Fork and clone the repository:
git clone https://github.com/YOUR_USERNAME/rugo.git
cd rugo
  1. Create a virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install development dependencies:
make update
  1. Compile the extension:
make compile
  1. Install in development mode:
pip install -e .

Development Workflow

Making Changes

  1. Create a new branch:
git checkout -b feature/your-feature-name

  1. Make your changes

  2. Run linters:

make lint
  1. Run tests:
make test
  1. Recompile if needed:
make compile

Code Style

We use several tools to maintain code quality:

  • ruff - Fast Python linter
  • isort - Import sorting
  • pycln - Remove unused imports
  • cython-lint - Cython code linting
  • mypy - Type checking

Run all linters:

make lint

Testing

Run the test suite:

make test

This runs pytest-based tests including comparisons with PyArrow to ensure correctness.

Type Checking

Run mypy for type checking:

make mypy

Contribution Guidelines

Code Contributions

  • Write clear, descriptive commit messages
  • Add tests for new features
  • Update documentation for API changes
  • Follow existing code style
  • Keep changes focused and atomic

Documentation Contributions

  • Use clear, concise language
  • Include code examples
  • Test code examples before submitting
  • Follow the existing documentation structure

Bug Reports

When reporting bugs, include:

  • Python version
  • Rugo version
  • Operating system
  • Minimal reproduction example
  • Expected vs actual behavior
  • Stack trace if applicable

Feature Requests

When requesting features:

  • Describe the use case
  • Explain why it's valuable
  • Provide examples if possible
  • Consider implementation complexity

Project Structure

rugo/
├── rugo/
│   ├── __init__.py
│   ├── parquet/
│   │   ├── metadata_reader.pyx  # Cython bindings
│   │   ├── metadata.cpp         # C++ parser
│   │   ├── metadata.hpp
│   │   ├── decode.cpp           # Decoder implementation
│   │   └── decode.hpp
│   └── converters/
│       └── orso.py              # Orso integration
├── tests/                       # Test suite
├── examples/                    # Example code
├── Makefile                     # Build automation
└── pyproject.toml              # Project configuration

Building the Extension

Full Rebuild

make compile

This: 1. Removes old build artifacts 2. Compiles with -O3 optimization 3. Uses C++17 standard 4. Builds in-place

Manual Build

python setup.py build_ext --inplace

Running Tests

All Tests

pytest

Specific Test File

pytest tests/test_all_metadata_fields.py

With Coverage

pytest --cov=rugo

Verbose Output

pytest -v

Pull Request Process

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Lint your code
  6. Commit with clear messages
  7. Push to your fork
  8. Submit a pull request

PR Checklist

  • [ ] Code follows project style
  • [ ] Tests pass
  • [ ] Linters pass
  • [ ] Documentation updated
  • [ ] Commit messages are clear
  • [ ] PR description explains changes

Getting Help

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

Code of Conduct

Please be respectful and professional. We aim to maintain a welcoming environment for all contributors.

Recognition

Contributors are recognized in: - Git commit history - Release notes - GitHub contributors page

Thank you for contributing to Rugo!