Contributing¶

Thank you for considering a contribution to waku! 🎉

This guide will help you get started and ensure a smooth process.

Getting Started¶

Prerequisites¶

Before you begin, ensure you have the following installed:

Python 3.11 or higher
uv – a modern Python package manager
Task – a task runner for automating development workflows (we recommend setting up auto-completion for Task)
Git

Development Setup¶

Fork and clone the repository:

git clone git@github.com:<your-username>/waku.git
cd waku

Install UV (if not already installed):

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# For other platforms, see:
# https://docs.astral.sh/uv/getting-started/installation/

# If uv is already installed, ensure it's up to date:
uv self update

Install Task (if not already installed):

# Using the install script
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

# For other installation options, see:
# https://taskfile.dev/installation/

Set up the development environment:
```
# Install dependencies and configure pre-commit hooks
task install
```
Tip: Run task -l after setup to verify everything is working and to see available commands.

Development Workflow¶

Making Changes¶

Fork the repository to your own GitHub account.

Clone your fork locally:

git clone git@github.com:<your-username>/waku.git
cd waku

Create a new branch for your changes:
```
git checkout -b feat/your-feature-name
```
Make your changes, following our code style guidelines.
Write or update tests for your changes.
Run all checks and ensure tests pass:
```
task
```
Commit your changes with clear, descriptive messages.
Push to your fork:
```
git push origin feat/your-feature-name
```
Open a pull request on GitHub. Link related issues in your PR description (e.g., "Fixes #123").
Participate in the review process and make any requested changes.

Pull Request Checklist¶

Tests added or updated
Documentation updated (if needed)
Code is formatted and linted
All checks pass
Type hints added or refined
Commit messages include a detailed description for the changelog

Testing¶

Ensure your changes are thoroughly tested by running the following commands:

# Run all checks (recommended)
task

# Run linters and type checkers
task check

# Run specific checks
task test         # Run tests only
task test:cov     # Run tests with coverage
task lint         # Run linters only
task format       # Format code
task typecheck    # Run type checkers only

Code Style¶

We use several tools to maintain code quality:

Ruff for linting and formatting
MyPy and basedpyright for type checking
pre-commit for running checks before commits and pushes

Key style guidelines:

Maximum line length: 120 characters
Use explicit type annotations throughout the codebase
Follow PEP 8 conventions
Write descriptive docstrings using the Google style

Getting Help¶

If you have questions or need help, you can:

Open a discussion
Open an issue for bugs or feature requests

First-time Contributors¶

Look for issues labeled "good first issue" or "help wanted".
Comment on the issue to let others know you're working on it.
Don't hesitate to ask questions if anything is unclear.

Issues¶

Before creating an issue:

Search existing issues to avoid duplicates.
Use the appropriate issue template for bug reports or feature requests.
Provide as much context as possible (e.g., steps to reproduce, environment details).

Please follow the bug report and feature request templates when submitting issues.

We welcome:

Bug reports
Feature requests
Documentation improvements
General questions or ideas

Project Structure¶

src/ – main source code
tests/ – test suite
docs/ – documentation
Taskfile.yml – development automation
README.md – project overview

Commit Message Guidelines¶

Use clear, descriptive commit messages.
Example: fix(core): handle edge case in dependency resolution

Thank you for contributing to waku! 🙏