Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
236 lines (174 loc) · 5.02 KB

CONTRIBUTING.md

File metadata and controls

236 lines (174 loc) · 5.02 KB
Raw

Contributing to Logly

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

Prerequisites

  • Rust: Latest stable (rustup update stable)
  • Python: 3.10+
  • uv: pip install uv
  • maturin: cargo install maturin

Development Setup

1. Fork the Repository

First, fork the Logly repository on GitHub by clicking the Fork button.

2. Clone Your Fork

git clone https://github.com/<your-username>/logly.git
cd logly

3. Add Upstream Remote

git remote add upstream https://github.com/muhammad-fiaz/logly.git

2. Create Virtual Environment

uv venv

3. Install Dependencies

uv sync

4. Build the Native Extension

uv run maturin develop

5. Install Pre-commit Hooks

uv run pre-commit install

Development Workflow

Before Making Changes

  1. Create a feature branch:

    git checkout -b feature/my-feature

  2. Ensure all checks pass:

    cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
ruff check .
ruff format --check .
uv run pytest -v

Making Changes

  1. Rust code (in crates/):

    • Follow existing code patterns
    • Add tests for new functionality
    • Run cargo fmt before committing

  2. Python code (in logly/):

    • Follow existing code patterns
    • Add type hints for new functions
    • Run ruff format before committing

  3. Documentation (in docs/):

    • Follow existing patterns
    • Test locally with uv run mkdocs serve

Running Tests

# Rust tests
cargo test --workspace

# Python tests
uv run pytest -v

# Specific test file
uv run pytest tests/test_logger.py -v

# With coverage
uv run pytest --cov=logly tests/

Linting and Formatting

# Check Rust formatting
cargo fmt --check

# Fix Rust formatting
cargo fmt

# Check Rust lints
cargo clippy --workspace --all-targets -- -D warnings

# Check Python linting
ruff check .

# Fix Python linting
ruff check --fix .

# Check Python formatting
ruff format --check .

# Fix Python formatting
ruff format .

Building Documentation

# Serve docs locally
uv run mkdocs serve

# Build docs
uv run mkdocs build

Project Structure

logly/
├── crates/              # Rust crates (monorepo)
│   ├── error/          # Error types
│   ├── config/         # Configuration
│   ├── levels/         # Log levels
│   ├── record/         # Log records
│   ├── color/          # ANSI colors
│   ├── format/         # Formatters
│   ├── filter/         # Filters
│   ├── rotate/         # File rotation
│   ├── compress/       # Compression
│   ├── concurrency/    # Background workers
│   ├── schedule/       # Scheduling
│   ├── context/        # Context management
│   ├── sink/           # Sinks
│   └── core/           # Dispatch engine
├── src/                # PyO3 bindings
├── logly/              # Python package
│   ├── logger.py      # Main Logger class
│   ├── models.py      # Pydantic config models
│   ├── exceptions.py  # Exception hierarchy
│   ├── integrations/  # FastAPI, Django, stdlib, Rich, telemetry
│   └── _logly.pyi    # Type stubs
├── tests/              # Python tests
├── examples/           # Usage examples
├── docs/               # Documentation source
└── site/               # Built documentation

Coding Standards

Rust

  • Use cargo fmt for consistent formatting
  • Use cargo clippy for lint checks
  • Add #[cfg(test)] mod tests for unit tests
  • Use ? for error propagation
  • Document public functions with /// comments

Python

  • Use ruff for linting and formatting
  • Add type hints for all public functions
  • Use __all__ for public API
  • Add docstrings for public classes and functions
  • Use dataclass or NamedTuple for simple data structures

Pull Request Process

  1. Update documentation if needed
  2. Add tests for new functionality
  3. Ensure all checks pass: 
    cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
ruff check .
ruff format --check .
uv run pytest -v
  4. Create a pull request with a clear description
  5. Reference any related issues

Reporting Issues

Bug Reports

  • Use the bug report template
  • Include steps to reproduce
  • Include your environment details

Feature Requests

  • Use the feature request template
  • Explain the use case
  • Provide examples if possible

Documentation Issues

  • Use the docs issue template
  • Specify which page needs updating
  • Provide the corrected content if possible

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and grow

Questions?

  • Open a discussion on GitHub
  • Use the help wanted template for specific issues