Contributing to Super Pocket

Thank you for your interest in contributing to Super Pocket! This guide will help you get started.

Code of Conduct

By participating in this project, you agree to:

Be respectful and inclusive
Welcome newcomers and help them learn
Focus on what is best for the community
Show empathy towards other community members

Getting Started

Setting Up Development Environment

Fork and Clone:

# Fork the repository on GitHub first
git clone https://github.com/YOUR-USERNAME/super-pocket.git
cd super-pocket

Create Virtual Environment:

# Using venv
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or using uv (recommended)
uv sync

Install Development Dependencies:

# Install with all dependencies
pip install -e ".[all,dev]"

# Or using uv
uv pip install -e ".[all,dev]"

Verify Installation:

# Run tests
pytest

# Check version
pocket --version

Creating a Branch

# Create a feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

How to Contribute

Reporting Bugs

Before creating a bug report:

Check existing issues
Verify you’re using the latest version
Test with minimal reproduction case

When creating a bug report, include:

Clear, descriptive title
Steps to reproduce
Expected vs actual behavior
Environment details (OS, Python version)
Error messages and tracebacks

Example bug report:

**Bug Description**
`pocket markdown render` crashes on files with emoji

**To Reproduce**
1. Create file with emoji: `echo "# 🚀 Test" > test.md`
2. Run: `pocket markdown render test.md`
3. See error

**Expected Behavior**
File renders correctly with emoji displayed

**Environment**
- OS: macOS 13.4
- Python: 3.11.4
- Super Pocket: 1.2.0

**Error Message**
```
UnicodeDecodeError: 'ascii' codec can't decode byte...
```

Suggesting Features

Feature requests should include:

Clear use case description
Why this feature would be useful
Proposed implementation (optional)
Examples of similar features elsewhere

Example feature request:

**Feature Request**
Add JSON export format for projects

**Use Case**
I need to export project structure as JSON for processing
with other tools and automation scripts.

**Proposed Solution**
Add `-f json` option to `pocket project to-file`:
```bash
pocket project to-file -f json -o project.json
```

**Alternatives**
Could pipe markdown output through converter, but native
support would be more efficient.

Contributing Code

Code Style

Super Pocket follows PEP 8 with these tools:

black - Code formatting
ruff - Linting
mypy - Type checking (optional)

Before committing:

# Format code
black pocket tests

# Check linting
ruff check pocket tests

# Type check (optional)
mypy pocket

Project automatically formats on commit with pre-commit hooks.

Type Hints

All new code should include type hints:

from typing import Optional, List
from pathlib import Path

def export_project(
    project_path: str | Path,
    output_file: str | Path,
    exclude: Optional[List[str]] = None
) -> None:
    """Export project to file.

    Args:
        project_path: Path to project directory
        output_file: Output file path
        exclude: Optional list of patterns to exclude
    """
    pass

Documentation

All public functions and classes need docstrings:

def function(param: str) -> bool:
    """Brief one-line description.

    Longer description explaining the function's purpose
    and behavior in more detail.

    Args:
        param: Description of the parameter

    Returns:
        Description of return value

    Raises:
        ValueError: When input is invalid

    Examples:
        >>> function("test")
        True
    """
    pass

Testing

All new features and bug fixes need tests:

import pytest
from src.super_pocket.markdown.renderer import render_markdown

def test_render_basic_markdown():
    """Test basic markdown rendering."""
    content = "# Hello World"
    result = render_markdown(content, from_string=True)
    assert "Hello World" in result

def test_render_missing_file():
    """Test handling of missing files."""
    with pytest.raises(FileNotFoundError):
        render_markdown("nonexistent.md")

Run tests:

# Run all tests
pytest

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

# Run specific test
pytest tests/unit_tests/test_markdown/test_renderer.py

See Testing Guide for detailed testing guidelines.

Commit Messages

Write clear, descriptive commit messages:

Add JSON export format for projects

- Implement JSONExporter class
- Add -f/--format option to CLI
- Include tests and documentation
- Update CHANGELOG.md

Closes #123

Format:

First line: Brief summary (50 chars max)
Blank line
Detailed description (72 chars per line)
Reference issues/PRs

Pull Request Process

Create Feature Branch:
```
git checkout -b feature/your-feature
```
Make Changes:
- Write code following style guide
- Add tests
- Update documentation
- Run linters and tests

Commit Changes:

git add .
git commit -m "Your descriptive message"

Push to Fork:
```
git push origin feature/your-feature
```
Create Pull Request:
- Go to GitHub and create PR
- Fill out PR template
- Link related issues
- Wait for review

Pull Request Checklist

Before submitting, ensure:

[ ] Code follows style guide (black, ruff)
[ ] All tests pass
[ ] New tests added for new features
[ ] Documentation updated
[ ] CHANGELOG.md updated
[ ] No merge conflicts
[ ] PR description is clear
[ ] Linked to related issues

Review Process

Your PR will be reviewed for:

Code quality and style
Test coverage
Documentation completeness
Backward compatibility
Performance implications

Be prepared to:

Answer questions
Make requested changes
Iterate on design

Contributing Documentation

Documentation improvements are highly valued!

Building Documentation

# Install sphinx dependencies
pip install -r docs/requirements.txt

# Build HTML documentation
cd docs
make html

# View in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux

Documentation Structure

docs/
├── conf.py              # Sphinx configuration
├── index.rst            # Homepage
├── installation.rst     # Installation guide
├── quickstart.rst       # Quick start guide
├── commands.rst         # Commands reference
├── api.rst              # API documentation
├── contributing.rst     # This file
├── _static/             # Static files (CSS, images)
└── _templates/          # Custom templates

Documentation Style

Use clear, concise language
Include code examples
Add screenshots where helpful
Cross-reference related sections
Follow reStructuredText format

Contributing Templates

Adding New Templates

Create Template File:

# Create in templates directory
touch pocket/documents/templates/your_agent.md

Write Template Content:

Follow this structure:

# Agent Name

## Purpose
Brief description

## Instructions
Detailed steps

## Examples
Code examples

Test Template:

# Verify it appears in list
pocket documents list

# Test viewing
pocket documents view your_agent

# Test copying
pocket documents copy your_agent -o /tmp/

Update Documentation:

Add your template to docs/templates.rst

Template Guidelines

Use clear, descriptive names
Include comprehensive instructions
Provide examples
Test thoroughly
Document use cases

Contributing Cheatsheets

Similar process to templates:

Create file in pocket/documents/cheatsheets/
Follow markdown format
Include comprehensive reference
Test with pocket documents view NAME -t cheatsheet

Release Process

For maintainers releasing new versions:

Update Version:

Update in pyproject.toml
Update Changelog:

Document all changes in CHANGELOG.md

Create Release:

git tag -a v1.0.2 -m "Release v1.0.2"
git push origin v1.0.2

Build and Publish:

# Build package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Community

Ways to Get Involved

Report bugs
Suggest features
Improve documentation
Write tutorials
Help other users
Review pull requests
Contribute code

Getting Help

GitHub Issues - Bug reports and features
Discussions - Questions and ideas
Documentation - Guides and references

Recognition

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
GitHub contributors page

Thank You!

Every contribution, no matter how small, is valuable and appreciated. Thank you for helping make Super Pocket better!