Contributing to Corgi

Welcome to the Corgi Recommender Service community! We're excited that you're interested in contributing to our privacy-first recommendation engine for the Fediverse. This guide will help you get started and ensure your contributions align with our project standards.

Getting Started

Finding Something to Work On

The best place to start is by exploring our GitHub issues:

• Good First Issues: Look for issues labeled good-first-issue - these are specifically chosen for new contributors
• Help Wanted: Issues labeled help-wanted need attention and are open for contribution
• Feature Requests: Browse enhancement labels for new feature ideas
• Bug Reports: Check bug labels to help fix existing issues

Join the Discussion

Before starting major work, comment on the issue to express interest. This helps avoid duplicate efforts and allows maintainers to provide guidance.

Setting Up Your Development Environment

1. Fork and Clone the Repository

   # Fork the repository on GitHub, then:
   git clone https://github.com/YOUR_USERNAME/corgi-recommender-service.git
   cd corgi-recommender-service
   

2. Set Up Python Environment

   # Create a virtual environment (recommended)
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install dependencies
   make install
   

3. Configure Environment Variables

   # Copy the example environment file
   cp env.example .env
   
   # Edit .env with your local configuration
   # Key variables: POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
   

4. Set Up the Database

   # Create and configure the PostgreSQL database
   ./setup_db.sh
   
   # For a fresh start (drops existing data):
   make reset-db
   

5. Install Development Workflow Dependencies

   # Install additional tools for automated testing
   make dev-install
   

6. Verify Your Setup

   # Run a quick health check
   make check
   
   # Start the development workflow
   make dev
   

Docker Alternative

If you prefer Docker, you can use docker-compose up instead of local setup. See our Docker guide for details.

Making Changes

Development Workflow

Our automated development workflow helps you catch issues early:

1. Start the Development Environment

   make dev  # Starts backend, frontend, and monitoring
   

This command provides: - Automatic API server startup - Real-time health monitoring - Browser testing capabilities - Immediate feedback on issues

1. Check Service Status

   make dev-status  # View what's running
   

2. Make Your Changes

3. Create a feature branch: git checkout -b feature/your-feature-name
4. Write your code following our conventions (see below)

5. Add or update tests as needed

6. Stop Services When Done

   make dev-stop  # Gracefully shut down all services
   

Where to Add Code

Understanding our project structure helps you put code in the right place:

corgi-recommender-service/
├── agents/           # AI agent implementations
├── routes/           # API endpoint handlers
├── utils/            # Shared utilities and helpers
├── core/             # Core recommendation algorithms
├── tasks/            # Celery background tasks
├── tests/            # Test files (mirror source structure)
├── db/               # Database models and migrations
└── frontend/         # Next.js frontend application

Examples: - New API endpoint? Add to routes/ - New agent? Create in agents/ - Utility function? Place in utils/ - Database model? Update db/models/

Testing Your Changes

Running Tests Locally

We use pytest for our test suite. Always run tests before submitting a PR:

1. Run All Tests

   pytest
   

2. Run Specific Test Files

   pytest tests/test_recommendations.py
   

3. Run with Coverage

   pytest --cov=. --cov-report=term-missing
   

4. Run Validation Suite

   make validate  # Comprehensive validation
   make dry-validate  # Dry run (no side effects)
   

Writing Tests

Every new feature or bug fix should include tests:

# Example test structure
def test_your_feature():
    """Test description of what this validates."""
    # Arrange
    setup_data = create_test_data()

    # Act
    result = your_function(setup_data)

    # Assert
    assert result.status == "success"
    assert result.data == expected_data

Test Organization

• Place tests in tests/ mirroring the source structure
• Use descriptive test names: test_recommendation_filters_nsfw_content
• Include both positive and negative test cases
• Mock external dependencies to ensure fast, reliable tests

Quality Checks

Our CI pipeline enforces several quality standards. Run these locally to catch issues early:

1. Code Formatting (Black)

   black --check --line-length 100 .
   # To auto-format: black --line-length 100 .
   

2. Import Sorting (isort)

   isort --check-only --profile black .
   # To auto-sort: isort --profile black .
   

3. Linting (flake8)

   flake8 . --max-line-length 100
   

4. Security Scanning

   pip-audit  # Check for vulnerable dependencies
   bandit -r . -ll  # Static security analysis
   

Submitting a Pull Request

Pre-Submission Checklist

Before opening a PR, ensure:

• [ ] All tests pass locally (pytest)
• [ ] Code follows our style guidelines (Black, isort)
• [ ] New features include tests
• [ ] Documentation is updated if needed
• [ ] Commit messages are clear and descriptive
• [ ] You've run make validate successfully

Creating the Pull Request

1. Push Your Branch

   git push origin feature/your-feature-name
   

2. Open a PR on GitHub

3. Use a clear, descriptive title
4. Reference any related issues: "Fixes #123"
5. Fill out the PR template completely

6. Add appropriate labels

7. PR Description Template

   ## Summary
   Brief description of changes
   
   ## Motivation
   Why these changes are needed
   
   ## Changes Made
   - List of specific changes
   - Implementation details
   
   ## Testing
   How you tested these changes
   
   ## Screenshots (if UI changes)
   Before/after screenshots
   

The Review Process

After submitting your PR:

1. Automated Checks: Our CI pipeline runs automatically
2. Must pass all 396+ tests (100% success required)
3. Security scans must pass

4. No performance regressions allowed

5. Code Review: A maintainer will review your code

6. Be responsive to feedback
7. Make requested changes promptly

8. Ask questions if something is unclear

9. Iteration: Most PRs require some back-and-forth

10. This is normal and helps maintain quality
11. Each iteration improves the code

Quality Gate

Our Quality Gate workflow requires 100% test success. Any failing test will block the merge. This ensures we maintain a stable, reliable codebase.

Code Style Guidelines

Python Style

We follow PEP 8 with some modifications:

• Line Length: 100 characters maximum
• Formatting: Enforced by Black
• Import Order: Enforced by isort (Black profile)
• Docstrings: Required for all public functions/classes

# Good example
def calculate_recommendation_score(
    user_profile: UserProfile,
    post: Post,
    algorithm_weights: Dict[str, float]
) -> float:
    """
    Calculate recommendation score for a post.

    Args:
        user_profile: User's preference profile
        post: Post to score
        algorithm_weights: Weight configuration for algorithms

    Returns:
        Normalized score between 0 and 1
    """
    # Implementation here

Commit Messages

Follow conventional commit format:

type(scope): brief description

Longer explanation if needed. Wrap at 72 characters.

Fixes #123

Types: feat, fix, docs, style, refactor, test, chore

Examples: - feat(recommendations): add temporal decay algorithm - fix(auth): handle expired tokens correctly - docs(api): update endpoint documentation

Error Handling

Always handle errors gracefully:

# Good
try:
    result = risky_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    return error_response(str(e))

# Avoid bare except
except:  # Don't do this!
    pass

Community Guidelines

Code of Conduct

We are committed to fostering an inclusive, welcoming community:

• Be Respectful: Treat everyone with respect and kindness
• Be Constructive: Provide helpful feedback and suggestions
• Be Patient: Remember that everyone was new once
• Be Inclusive: Welcome diverse perspectives and experiences

Getting Help

If you need assistance:

1. Documentation: Check our comprehensive docs first
2. GitHub Discussions: Ask questions in the Q&A section
3. Issues: For bugs or feature requests
4. Code Comments: When in doubt, over-communicate in your code

Recognition

We value all contributions:

• Your name will be added to CONTRIBUTORS.md
• Significant contributions are highlighted in release notes
• Active contributors may be invited to join the maintainer team

Advanced Topics

Working with Agents

If you're adding or modifying AI agents:

1. Inherit from BaseAgent
2. Implement required methods
3. Add cost tracking
4. Include safety controls
5. Document behavior thoroughly

class YourNewAgent(BaseAgent):
    """Agent description and purpose."""

    async def execute(self) -> AgentResult:
        """Execute agent logic with safety controls."""
        # Implementation

Database Migrations

For schema changes:

1. Create a migration file in db/migrations/
2. Follow the naming pattern: XXX_description.sql
3. Test migration and rollback locally
4. Document any data transformations

Performance Considerations

Keep Corgi fast:

• Profile code for operations over 100ms
• Use caching where appropriate
• Batch database operations
• Consider async for I/O operations
• Add performance tests for critical paths

Thank You!

Your contributions make Corgi better for everyone in the Fediverse. We're grateful for your time and effort in improving our privacy-first recommendation engine.

Welcome to the pack! 🐕

---

Quick Links

• Issue Tracker
• Discussions
• Documentation
• Code of Conduct