Skip to content

Contributing to Ravyn

Thank you for your interest in contributing to Ravyn! We welcome contributions from the community and appreciate your help in making Ravyn better.

What You'll Learn

  • How to set up your development environment with hatch
  • Contribution workflow and guidelines
  • Code style and testing requirements
  • How to submit pull requests
  • Where to get help

Quick Start

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/ravyn.git
cd ravyn

# 2. Install hatch
pip install hatch

# 3. Create development environments (optional, hatch does this automatically)
hatch env create
hatch env create test
hatch env create docs

# 4. Run tests to verify setup
hatch run test:test

# 5. Create a branch for your changes
git checkout -b feature/my-awesome-feature

# 6. Make your changes and test
hatch run test:test
hatch run lint

# 7. Commit and push
git add .
git commit -m "Add awesome feature"
git push origin feature/my-awesome-feature

# 8. Open a pull request on GitHub

Ways to Contribute

🐛 Report Bugs

Found a bug? Please start with a discussion as "Potential Issue":

  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Your environment (OS, Python version, Ravyn version)
  • Code snippets and tracebacks

Suggest Features

Have an idea? Open a discussion as "Ideas":

  • Clear description of the feature
  • Use cases and benefits
  • Proposed implementation (if you have ideas)

📝 Improve Documentation

Documentation improvements are always welcome:

  • Fix typos or unclear explanations
  • Add examples
  • Improve existing guides
  • Write tutorials

🔧 Submit Code

Code contributions should:

  • Fix bugs
  • Add new features
  • Improve performance
  • Enhance existing functionality

Development Setup

Prerequisites

  • Python 3.8 or higher
  • Git
  • A GitHub account

Installation

# Fork the repository on GitHub first, then:

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ravyn.git
cd ravyn

# Add upstream remote
git remote add upstream https://github.com/dymmond/ravyn.git

# Install hatch
pip install hatch

[!INFO] Ravyn uses hatch for development, testing, and release cycles.

Initialize Environments (Optional)

Hatch automatically creates environments when needed, but you can pre-initialize them:

# Create all environments
hatch env create
hatch env create test
hatch env create docs

Tip

If you prefer your own virtual environment with all packages installed, you can run scripts/install.

Verify Installation

# Run tests
hatch run test:test

# Run linting
hatch run lint

# Check formatting
hatch run format

Contribution Workflow

1. Create a Discussion

Before starting work, create a discussion to talk about your changes.

2. Fork and Branch

# Update your fork
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/my-feature
# or
git checkout -b fix/bug-description

3. Make Changes

  • Write clean, readable code
  • Follow the code style guidelines
  • Add tests for new functionality
  • Update documentation as needed

4. Test Your Changes

# Run all tests
hatch run test:test

# Run specific test file
hatch run test:test tests/test_routing.py

# Run linting
hatch run lint

# Format code
hatch run format

5. Enable Pre-commit (Optional)

# Install pre-commit hooks
pre-commit install

6. Commit Your Changes

# Stage changes
git add .

# Commit with descriptive message
git commit -m "Add feature: description of what you did"

Commit Message Guidelines: - Use present tense ("Add feature" not "Added feature") - Be descriptive but concise - Reference issue numbers when applicable

Examples: 

Add support for WebSocket connections (#123)
Fix validation error in request handling (#456)
Update documentation for caching system

7. Push and Create Pull Request

# Push to your fork
git push origin feature/my-feature

Then open a pull request on GitHub with:

  • Clear title describing the change
  • Description of what changed and why
  • Reference to related discussions/issues
  • Screenshots (if UI changes)

Testing

Running Tests

# All tests
hatch run test:test

# Specific file
hatch run test:test tests/test_routing.py

# With coverage
hatch run test:test --cov=ravyn --cov-report=html

# Verbose output
hatch run test:test -v

[!INFO] Ravyn uses pytest. Any additional arguments are passed directly to pytest.

Writing Tests

import pytest
from ravyn import Ravyn, get

def test_simple_route():
    """Test basic route functionality."""
    app = Ravyn()

    @get("/hello")
    def hello() -> dict:
        return {"message": "Hello, World!"}

    app.add_route(hello)

    from ravyn import RavynTestClient

    with RavynTestClient(app) as client:
        response = client.get("/hello")
        assert response.status_code == 200
        assert response.json() == {"message": "Hello, World!"}

Documentation

Building Documentation

# Build all documentation
hatch run docs:build

# Build specific language
hatch run docs:build_lang en

Serving Documentation Locally

# Serve docs with live reload
hatch run docs:serve

# Serve on specific port
hatch run docs:serve -p 8080

# Serve specific language
hatch run docs:serve_lang es

The documentation will be available at http://localhost:8000.

Tip

You can also manually run mkdocs serve in the docs/en/ directory.

Documentation Structure

  • Documentation uses MkDocs
  • All docs are in Markdown format in ./docs/en/
  • Code examples are in ./docs_src/ directory
  • Code blocks are included/injected when generating the site

Code Style

Linting and Formatting

# Run linting
hatch run lint

# Format code
hatch run format

Python Style

We follow PEP 8 with some modifications:

# Good
class UserController:
    """Handle user-related operations."""

    async def get_user(self, user_id: int) -> dict:
        """
        Get user by ID.

        Args:
            user_id: The user's ID

        Returns:
            User data dictionary
        """
        user = await self.db.fetch_one("SELECT * FROM users WHERE id = ?", user_id)
        return user

Type Hints

Always use type hints:

# Good
async def create_user(name: str, email: str) -> dict:
    pass

# Bad - no type hints
async def create_user(name, email):
    pass

Building Ravyn

Local Build

# Build package locally
hatch build

# Or create a shell with installed package
hatch shell

TaskFile (Alternative)

Ravyn also supports TaskFile as an alternative to hatch commands:

# List all available tasks
task

# Run tests manually
task test_man ARGS=tests/msgspec/

Warning

TaskFile support may be discontinued in the future for a better alternative.

Pull Request Guidelines

Before Submitting

  • [ ] Tests pass locally
  • [ ] Code follows style guidelines
  • [ ] Documentation updated
  • [ ] Commit messages are clear
  • [ ] Branch is up to date with main

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Related Discussions/Issues
Relates to #123

## Testing
Describe how you tested your changes

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guidelines

Translations

Help with translations is very much appreciated!

Tips and Guidelines

Translating Existing Language

# Serve docs for specific language (e.g., Spanish)
hatch run docs:serve_lang es

Then copy files from docs/en/docs/ to docs/es/docs/ and translate.

Adding New Language

# Create new language directory (e.g., Creole with code 'ht')
hatch run docs:new_lang ht

This creates docs/ht/mkdocs.yml and docs/ht/index.md to get started.

Getting Help

Community

  • GitHub Discussions: Ask questions and share ideas
  • Issues: Report bugs and request features
  • Pull Requests: Review and contribute code

Resources

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

Do: - Be respectful and constructive - Welcome newcomers - Give credit where due - Focus on what's best for the community

Don't: - Use offensive language - Make personal attacks - Harass others - Share private information

Releasing

This section is for the maintainers of Ravyn.

Building the Ravyn for release

Before releasing a new package into production some considerations need to be taken into account.

  • Changelog

    • Like many projects, we follow the format from keepchangelog.
    • Compare main with the release tag and list of the entries that are of interest to the users of the framework.
      • What must go in the changelog? added, changed, removed or deprecated features and the bug fixes.
      • What is should not go in the changelog? Documentation changes, tests or anything not specified in the point above.
      • Make sure the order of the entries are sorted by importance.
      • Keep it simple.

  • Version bump

    • The version should be in __init__.py of the main package.

Releasing

Once the release PR is merged, create a new release that includes:

Example:

There will be a release of the version 0.2.3, this is what it should include.

  • Release title: Version 0.2.3.
  • Tag: 0.2.3.
  • The description should be copied from the changelog.

Once the release is created, it should automatically upload the new version to PyPI. If something does not work with PyPI the release can be done by running scripts/release.

Thank You!

Your contributions make Ravyn better for everyone. We appreciate your time and effort! ---

Next Steps