Skip to content

Latest commit

 

History

History
429 lines (304 loc) · 8.24 KB

CONTRIBUTING.md

File metadata and controls

429 lines (304 loc) · 8.24 KB

Contributing to SocialPie

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

Table of Contents

Code of Conduct

Be respectful, constructive, and professional in all interactions.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/SocialPie.git
cd SocialPie
  3. Add upstream remote: 
    git remote add upstream https://github.com/EricsonWillians/SocialPie.git

Development Setup

Install Development Dependencies

# Create virtual environment
python3.10 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all extras
pip install -e ".[all,dev]"

# Install pre-commit hooks
pre-commit install

Verify Setup

# Run type checking
mypy src/socialpie

# Run linting
ruff check src/socialpie

# Run formatting check
black --check src/socialpie

# Run tests
pytest

Making Changes

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

2. Make Your Changes

  • Write clean, typed Python code
  • Follow the existing code style
  • Add tests for new functionality
  • Update documentation as needed

3. Run Pre-commit Hooks

# Hooks run automatically on commit, or run manually:
pre-commit run --all-files

Testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=socialpie --cov-report=html

# Run specific test file
pytest tests/test_protocol.py

# Run specific test
pytest tests/test_protocol.py::TestMessage::test_create_message

# Run in verbose mode
pytest -v

# Run with output
pytest -s

Writing Tests

  • Place tests in the tests/ directory
  • Name test files test_*.py
  • Name test classes Test*
  • Name test methods test_*
  • Use pytest fixtures for setup
  • Aim for 80%+ code coverage

Example test:

import pytest
from socialpie.core.protocol import Message, MessageType

class TestMessage:
    def test_create_message(self) -> None:
        """Test creating a message."""
        message = Message(
            type=MessageType.CHAT,
            user="Alice",
            content="Hello!",
        )

        assert message.type == MessageType.CHAT
        assert message.user == "Alice"
        assert message.content == "Hello!"

Code Style

Type Hints

All code must have complete type hints:

from typing import Optional, List, Dict, Any

def process_message(
    message: str,
    user: str,
    metadata: Optional[Dict[str, Any]] = None
) -> List[str]:
    """Process a message and return tokens."""
    ...

Formatting

  • Line length: 100 characters
  • Imports: Sorted with isort
  • Code: Formatted with black
  • Docstrings: Google style

Example:

"""Module docstring explaining what this module does."""

from typing import Optional

import structlog

from socialpie.core.protocol import Message


logger = structlog.get_logger(__name__)


class MyClass:
    """Class docstring.

    Attributes:
        name: The name attribute.
        value: The value attribute.
    """

    def __init__(self, name: str, value: int) -> None:
        """Initialize the class.

        Args:
            name: Name parameter.
            value: Value parameter.
        """
        self.name = name
        self.value = value

    def process(self, data: str) -> Optional[str]:
        """Process data and return result.

        Args:
            data: Input data to process.

        Returns:
            Processed result or None if processing failed.

        Raises:
            ValueError: If data is invalid.
        """
        if not data:
            raise ValueError("Data cannot be empty")
        return data.upper()

Linting

Code must pass:

  • mypy strict mode (no type errors)
  • ruff (no linting errors)
  • black (properly formatted)
  • isort (imports sorted)

Submitting Changes

1. Commit Your Changes

# Add files
git add .

# Commit with descriptive message
git commit -m "Add feature: description of changes

- Detailed point 1
- Detailed point 2

Fixes #123"

Commit Message Format

<type>: <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Example:

feat: Add dice roller plugin

- Implement dice notation parser (XdY+Z)
- Add /roll command
- Support multiple dice types
- Add validation for maximum dice/sides

Closes #42

2. Push to Your Fork

git push origin feature/your-feature-name

3. Create Pull Request

  1. Go to your fork on GitHub
  2. Click "Pull Request"
  3. Select your branch
  4. Fill in the template:
    • Description: What changes does this PR make?
    • Motivation: Why is this change needed?
    • Testing: How has this been tested?
    • Screenshots: If UI changes, include screenshots

4. Code Review

  • Address reviewer feedback
  • Make requested changes
  • Push updates to your branch (PR updates automatically)

Plugin Development

Creating a Plugin

See PLUGIN_DEVELOPMENT_GUIDE.md for detailed instructions.

Quick start:

# Create plugin directory
mkdir -p plugins/community/my-plugin

# Create plugin structure
cd plugins/community/my-plugin
touch __init__.py plugin.py plugin.yaml README.md

Plugin Guidelines

  1. Follow the plugin structure:

    • plugin.yaml - Manifest with metadata
    • plugin.py - Main plugin code
    • __init__.py - Package init
    • README.md - Documentation

  2. Use type hints: All plugin code must be fully typed

  3. Handle errors: Use try/except and log errors appropriately

  4. Document: Add docstrings and README

  5. Test: Include tests in tests/ directory

  6. Configuration: Use config schema for validation

Submitting Plugins

Official plugins go in plugins/official/:

  1. Must be high quality
  2. Must have comprehensive tests
  3. Must have good documentation
  4. Must follow all coding standards

Community plugins go in plugins/community/:

  1. More relaxed requirements
  2. Should have basic tests
  3. Should have README
  4. Must work correctly

Development Tips

Useful Commands

# Watch tests
ptw  # If you have pytest-watch

# Format all code
black src/socialpie tests
isort src/socialpie tests

# Type check
mypy src/socialpie

# Lint
ruff check src/socialpie --fix

# Run specific test with output
pytest -svv tests/test_protocol.py::TestMessage::test_create_message

# Generate coverage report
pytest --cov=socialpie --cov-report=html
open htmlcov/index.html

Debugging

Use structlog for logging:

import structlog

logger = structlog.get_logger(__name__)

# Log with context
logger.debug("processing_message", user=user, length=len(content))
logger.info("message_sent", message_id=msg.id)
logger.warning("rate_limit_exceeded", user=user, limit=limit)
logger.error("failed_to_send", error=str(e), exc_info=True)

IDE Setup

VS Code

Install extensions:

  • Python
  • Pylance
  • Black Formatter
  • isort
  • Mypy Type Checker

Settings (.vscode/settings.json):

{
  "python.linting.enabled": true,
  "python.linting.mypyEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "python.analysis.typeCheckingMode": "strict"
}

PyCharm

  1. Enable type checking in settings
  2. Configure Black as external tool
  3. Set line length to 100
  4. Enable auto-import optimization

Questions?

  • GitHub Discussions: Ask questions
  • Issues: Report bugs or request features
  • Discord: Join the community (if available)

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0-or-later license.

Thank you for contributing to SocialPie! 🎉