Skip to content

Contributing to Recursivist

Thank you for your interest in contributing to Recursivist! This document provides guidelines and instructions for contributing to this project.

Table of Contents

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please be respectful, inclusive, and considerate when interacting with other contributors.

Getting Started

Setting Up Your Development Environment

  1. Fork the repository:

  2. Visit the Recursivist repository and click the "Fork" button to create your own copy.

  3. Clone your fork:

git clone https://github.com/ArmaanjeetSandhu/recursivist.git
cd recursivist
  1. Set up the upstream remote:
git remote add upstream https://github.com/ArmaanjeetSandhu/recursivist.git
  1. Create a virtual environment:
python -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate
  1. Install development dependencies: 
    pip install -e ".[dev]"

Development Workflow

Creating a Branch

  1. Make sure your fork is up to date:
git checkout main
git pull upstream main
git push origin main
  1. Create a new branch for your feature or bugfix: 
    git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Making Changes

  1. Make your changes to the codebase according to our coding standards.

  2. Commit your changes with clear and descriptive commit messages:

git add .
git commit -m "Add feature: description of what you added"
  1. Keep your branch updated with the upstream repository: 
    git pull upstream main

Testing Your Changes

  1. Run the tests to make sure your changes don't break existing functionality:
pytest
  1. Test the CLI to verify it works as expected: 
    python -m recursivist --help

Submitting a Pull Request

  1. Push your branch to your fork:
git push origin feature/your-feature-name

  1. Create a Pull Request from your fork to the main repository:

  2. Go to the Recursivist repository

  3. Click "Pull Requests" > "New Pull Request"
  4. Select "compare across forks" and choose your fork and branch

  5. Click "Create Pull Request"

  6. Describe your changes in the PR:

  7. What problem does it solve?

  8. How can it be tested?

  9. Any dependencies or breaking changes?

  10. Address review feedback if requested by maintainers.

Coding Standards

Code Style

We follow PEP 8 and use the following tools to maintain code quality:

  • Black for code formatting:
pip install black
black recursivist/
  • Flake8 for linting:
pip install flake8
flake8 recursivist/
  • isort for import sorting:
pip install isort
isort recursivist/
  • mypy for type checking:
pip install mypy
mypy recursivist/

Documentation

  • Write docstrings for all public modules, functions, classes, and methods.
  • Follow the Google docstring style as shown in existing code.

Example docstring:

def function(arg1: str, arg2: int) -> bool:
    """A short description of the function.

    A more detailed description explaining the behavior, edge cases, and implementation details if relevant.

    Args:
        arg1: Description of the first argument
        arg2: Description of the second argument

    Returns:
        Description of the return value

    Raises:
        ValueError: When the input is invalid
    """

Type Annotations

We use Python type hints for better code quality and IDE support:

from typing import Dict, List, Optional, Set

def process_data(data: Dict[str, List[str]],
                 options: Optional[Set[str]] = None) -> bool:
    # Function implementation
    return True

Testing

Running Tests

We use pytest for testing:

# Run all tests
pytest

# Run with coverage report
pytest --cov=recursivist

# Run tests from a specific file
pytest tests/test_core.py

Writing Tests

  • Write tests for all new features and bug fixes.
  • Place tests in the tests/ directory with a name that matches the module being tested.
  • Follow the test style used in existing tests.

Example test:

# tests/test_core.py
from recursivist.core import generate_color_for_extension

def test_generate_color_for_extension():
    # Given
    extension = ".py"

    # When
    color = generate_color_for_extension(extension)

    # Then
    assert isinstance(color, str)
    assert color.startswith("#")
    assert len(color) == 7

Bug Reports and Feature Requests

Reporting Bugs

Please report bugs by opening an issue on GitHub with the following information:

  • A clear and descriptive title
  • Steps to reproduce the issue
  • Expected behavior
  • Actual behavior
  • Environment details (OS, Python version, etc.)
  • Any relevant logs or screenshots

Suggesting Features

We welcome feature requests! Please open an issue with:

  • A clear and descriptive title
  • A detailed description of the proposed feature
  • Any relevant examples or use cases
  • Information about why this feature would be useful

Release Process

  1. Version bump:

  2. Update version in __init__.py and pyproject.toml

  3. Update the changelog

  4. Create a release commit:

git add .
git commit -m "Release v0.2.0"
git tag v0.2.0
git push origin main --tags
  1. Build and publish: 
    python -m build
python -m twine upload dist/*

Community

  • GitHub Discussions: Use this for questions and general discussion.
  • Issues: Bug reports and feature requests.
  • Pull Requests: Submit changes to the codebase.

Thank you for contributing to Recursivist! Your efforts help make this project better for everyone.