wikijs-sdk-python/docs/CONTRIBUTING.md

Contributing to Wiki.js Python SDK

Thank you for your interest in contributing to the Wiki.js Python SDK! This guide will help you get started with contributing to this community-driven project.

🎯 Project Context

This project was developed by leomiranda, showcasing professional development practices while building a production-ready SDK for Wiki.js. We welcome contributors of all experience levels!

Current Status: MVP Development (Phase 1)
Focus: Core functionality and foundational quality

🚀 Getting Started

Prerequisites

• Python 3.8 or higher
• Git
• A GitHub account
• (Optional) A Wiki.js instance for testing

Development Setup

1. Fork the Repository

   # Fork on Gitea, then clone your fork
   git clone https://gitea.hotserv.cloud/lmiranda/wikijs-sdk-python.git
   cd wikijs-python-sdk
   

2. Set Up Development Environment

   # Create virtual environment
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install in development mode
   pip install -e ".[dev]"
   
   # Install pre-commit hooks
   pre-commit install
   

3. Verify Setup

   # Run tests
   pytest
   
   # Run quality checks
   pre-commit run --all-files
   

📋 Development Process

Finding Work

1. Check Current Priorities

   • Review CLAUDE.md for current development tasks
   • See Development Plan for roadmap
   • Look for issues in the Gitea repository

2. Understand Architecture

   • Read Architecture Overview
   • Review existing code patterns
   • Check the Risk Management for known issues

Making Changes

1. Create Feature Branch

   git checkout -b feature/your-feature-name
   

2. Follow Code Standards

   • Write type hints for all public APIs
   • Add docstrings to all public methods (Google style)
   • Follow existing code patterns
   • Keep functions small and focused

3. Write Tests

   • Add unit tests for new functionality
   • Maintain >85% code coverage
   • Use descriptive test names
   • Include edge cases

4. Update Documentation

   • Update docstrings for changed methods
   • Add examples for new features
   • Update README if needed

Code Quality Standards

Python Style

def example_function(param: str, optional: Optional[int] = None) -> bool:
    """Example function following our standards.
    
    Args:
        param: Description of the parameter
        optional: Optional parameter with default
        
    Returns:
        Boolean result of the operation
        
    Raises:
        ValueError: If param is empty
        
    Example:
        >>> example_function("test")
        True
    """
    if not param:
        raise ValueError("param cannot be empty")
    
    # Implementation here
    return True

Testing Patterns

import pytest
from wikijs import WikiJSClient
from wikijs.exceptions import WikiJSException

class TestWikiJSClient:
    """Test WikiJS client functionality."""
    
    def test_client_initialization_success(self):
        """Test successful client initialization."""
        client = WikiJSClient("https://wiki.example.com", "api-key")
        assert client.base_url == "https://wiki.example.com"
    
    def test_client_initialization_invalid_url(self):
        """Test client initialization with invalid URL."""
        with pytest.raises(ValueError, match="Invalid URL"):
            WikiJSClient("invalid-url", "api-key")

Submitting Changes

1. Run Quality Checks

   # Format code
   black wikijs tests
   isort wikijs tests
   
   # Run linting
   flake8 wikijs tests
   mypy wikijs
   
   # Run tests
   pytest --cov=wikijs --cov-fail-under=85
   
   # Security scan
   bandit -r wikijs
   

2. Commit Changes

   git add .
   git commit -m "feat: add new feature description
   
   Detailed description of what was changed and why.
   
   Closes #123"
   

3. Create Pull Request

   • Push to your fork
   • Create PR against main branch
   • Fill out the PR template completely
   • Link related issues

🤝 Community Guidelines

Communication

• Be respectful and constructive in all interactions
• Ask questions if anything is unclear
• Help others when you can
• Focus on the code, not the person

Code Review Process

1. Maintainer Review: All PRs reviewed by project maintainer
2. Feedback: Address review comments promptly
3. Discussion: Open discussion encouraged for design decisions
4. Approval: PR approved when all checks pass and review complete

Response Times

• Issues: Response within 48-72 hours
• Pull Requests: Initial review within 1 week
• Questions: Community-driven with maintainer backup

🏗️ Architecture & Patterns

Project Structure

wikijs/
├── __init__.py          # Package entry point
├── client.py            # Main client class
├── exceptions.py        # Exception hierarchy
├── models/              # Data models (Pydantic)
├── auth/                # Authentication handlers
├── endpoints/           # API endpoint implementations
└── utils/               # Utility functions

Key Patterns

• Dependency Injection: Use abstract interfaces
• Type Safety: Full type hints and validation
• Error Handling: Comprehensive exception hierarchy
• Testing: Mock external dependencies
• Documentation: Example-driven docstrings

🧪 Testing Guidelines

Test Categories

• Unit Tests: Test individual components in isolation
• Integration Tests: Test component interactions
• End-to-End: Test with real Wiki.js instance (CI only)

Test Organization

tests/
├── unit/
│   ├── test_client.py
│   ├── test_models.py
│   └── test_auth.py
├── integration/
│   └── test_api_endpoints.py
└── conftest.py          # Shared fixtures

Writing Good Tests

def test_specific_behavior_with_expected_outcome():
    """Test description should be clear and specific."""
    # Arrange
    client = WikiJSClient("https://example.com", "key")
    
    # Act
    result = client.some_method()
    
    # Assert
    assert result.expected_property == "expected_value"

🐛 Bug Reports

Before Reporting

1. Check existing issues
2. Test with latest version
3. Provide minimal reproduction case

Bug Report Checklist

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Environment details
• Error messages/stack traces
• Minimal code example

✨ Feature Requests

Before Requesting

1. Check if feature already exists
2. Search existing feature requests
3. Consider if it fits project scope

Feature Request Checklist

• Clear use case description
• Proposed API design
• Implementation considerations
• Breaking change analysis

🚢 Release Process

Releases are managed by maintainers:

1. Version Bump: Update version in wikijs/version.py
2. Changelog: Update docs/CHANGELOG.md with changes
3. Tag Release: Create git tag v0.1.0
4. Automated: GitHub Actions handles testing and GitHub release creation

📚 Documentation

Types of Documentation

• API Reference: Auto-generated from docstrings
• User Guides: How-to guides and tutorials
• Examples: Real-world usage examples
• Architecture: Technical design decisions

Documentation Standards

• Write for your audience (users vs contributors)
• Include practical examples
• Keep it up-to-date with code changes
• Use clear, concise language

📋 Development Context

This project was developed by leomiranda with careful coordination and planning. If you're interested in the development process:

• See CLAUDE.md for development coordination details
• Development tasks are tracked and managed systematically
• Quality standards are maintained through automated tooling
• Community contributions are integrated with systematic development processes

❓ Getting Help

Questions and Support

• GitHub Discussions: General questions and community chat
• GitHub Issues: Bug reports and feature requests
• Documentation: Check docs for existing answers
• Code Review: Learn through the review process

Common Questions

Q: How do I set up a test Wiki.js instance? A: Check the testing documentation for local setup instructions.

Q: What should I work on first? A: Look for good first issue labels or check CLAUDE.md for current priorities.

Q: How do I add a new API endpoint? A: Follow the existing patterns in wikijs/endpoints/ and add corresponding tests.

🙏 Recognition

All contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes for significant contributions
• GitHub contributors page

Significant contributors may be invited to become maintainers.

---

Ready to contribute?

1. Read our Governance guidelines
2. Check the current development status
3. Look for issues in the repository
4. Join the discussion!

Questions? Don't hesitate to create an issue in the Gitea repository.