Contributing to SanctumOS

Thank you for your interest in contributing to SanctumOS! This guide will help you get started with contributing to the project.

🎯 How to Contribute

Types of Contributions

Code Contributions: Bug fixes, features, and improvements
Documentation: Help improve our documentation
Testing: Help us test and validate new features
Feedback: Share your experiences and suggestions
Community: Help others in the community

Getting Started

Fork the Repository: Fork the relevant SanctumOS repository
Clone Your Fork: Clone your fork to your local machine
Create a Branch: Create a feature branch for your changes
Make Changes: Implement your changes
Test: Test your changes thoroughly
Submit Pull Request: Submit a pull request with your changes

🏗️ Development Setup

Prerequisites

Python 3.8 or higher
Git
Basic understanding of the SanctumOS architecture
Familiarity with the module you're contributing to

Setting Up Development Environment

# Clone your fork
git clone https://github.com/your-username/sanctumos-repo.git
cd sanctumos-repo

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

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Set up pre-commit hooks
pre-commit install

Clone your fork

git clone https://github.com/your-username/sanctumos-repo.git cd sanctumos-repo

Create virtual environment

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

Install dependencies

pip install -r requirements.txt pip install -r requirements-dev.txt

Set up pre-commit hooks

pre-commit install


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


Development Workflow
Create Feature Branch:
   git checkout -b feature/your-feature-name
git checkout -b feature/your-feature-name


2. Make Changes: Implement your changes with proper testing

3. Run Tests:
   bash
   # Run all tests
   python -m pytest tests/ -v
   
   # Run specific test categories
   python -m pytest tests/unit/ -v
   python -m pytest tests/integration/ -v

Make Changes: Implement your changes with proper testing

Run Tests:

   git checkout -b feature/your-feature-name

Run all tests

python -m pytest tests/ -v

Run specific test categories

python -m pytest tests/unit/ -v python -m pytest tests/integration/ -v


2. Make Changes: Implement your changes with proper testing

3. Run Tests:
   bash
   # Run all tests
   python -m pytest tests/ -v
   
   # Run specific test categories
   python -m pytest tests/unit/ -v
   python -m pytest tests/integration/ -v


Code Quality Checks:
   git checkout -b feature/your-feature-name
Linting
flake8 . --exclude=venv
Type checking
mypy .
Format code
black .


2. Make Changes: Implement your changes with proper testing

3. Run Tests:
   bash
   # Run all tests
   python -m pytest tests/ -v
   
   # Run specific test categories
   python -m pytest tests/unit/ -v
   python -m pytest tests/integration/ -v

Commit Changes:

   git checkout -b feature/your-feature-name

git add . git commit -m "Add feature: brief description"


2. Make Changes: Implement your changes with proper testing

3. Run Tests:
   bash
   # Run all tests
   python -m pytest tests/ -v
   
   # Run specific test categories
   python -m pytest tests/unit/ -v
   python -m pytest tests/integration/ -v


Push and Create PR:
   git checkout -b feature/your-feature-name
git push origin feature/your-feature-name
Create pull request on GitHub


2. Make Changes: Implement your changes with proper testing

3. Run Tests:
   bash
   # Run all tests
   python -m pytest tests/ -v
   
   # Run specific test categories
   python -m pytest tests/unit/ -v
   python -m pytest tests/integration/ -v

📝 Coding Standards

Code Style

Python: Follow PEP 8 style guide
Documentation: Use clear, concise documentation
Comments: Add comments for complex logic
Type Hints: Use type hints for function parameters and return values

Code Quality

Testing: Write tests for all new functionality
Error Handling: Implement proper error handling
Logging: Use appropriate logging levels
Security: Consider security implications of changes

Documentation

Docstrings: Add docstrings to all functions and classes
README Updates: Update README files for significant changes
API Documentation: Update API documentation for API changes
Examples: Provide examples for new features

🧪 Testing

Test Categories

Unit Tests: Test individual functions and classes
Integration Tests: Test component interactions
End-to-End Tests: Test complete workflows
Performance Tests: Test performance characteristics

Writing Tests

import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)

import pytest from your_module import YourClass

class TestYourClass: def test_basic_functionality(self): """Test basic functionality.""" instance = YourClass() result = instance.method() assert result == expected_value

def test_error_handling(self): """Test error handling.""" instance = YourClass() with pytest.raises(ValueError): instance.method(invalid_input)


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


Running Tests
# Clone your fork
git clone https://github.com/your-username/sanctumos-repo.git
cd sanctumos-repo

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

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Set up pre-commit hooks
pre-commit install
Run all tests
python -m pytest tests/ -v
Run with coverage
python -m pytest tests/ --cov=. --cov-report=html
Run specific test file
python -m pytest tests/test_specific.py -v


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

🔌 Plugin Development

Creating Plugins

MCP Plugins

import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)

#!/usr/bin/env python3 """ Your Plugin CLI

A sample plugin for the Sanctum Letta MCP Server. """

import argparse import json import sys

def main(): parser = argparse.ArgumentParser(description="Your Plugin CLI") subparsers = parser.add_subparsers(dest="command", help="Available commands")

Add your command

cmd_parser = subparsers.add_parser("your-command", help="Execute your command") cmd_parser.add_argument("--param", required=True, help="Required parameter")

args = parser.parse_args()

if args.command == "your-command": result = execute_your_command(args.param) print(json.dumps(result)) else: parser.print_help() sys.exit(1)

def execute_your_command(param): """Execute the main command logic."""

Your plugin logic here

return { "status": "success", "param": param, "message": "Command executed successfully" }

if __name__ == "__main__": main()


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


Broca Plugins
import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)
from plugins import Plugin
class YourPlatformPlugin(Plugin): def get_name(self) -> str: return "your_platform"
def get_platform(self) -> str: return "your_platform"
def get_message_handler(self) -> Callable: return self._handle_message
async def start(self) -> None:
Initialize plugin
pass
async def stop(self) -> None:
Cleanup plugin
pass
async def _handle_message(self, message):
Process incoming messages
pass


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

Plugin Testing

import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)

import pytest from your_plugin import YourPlugin

class TestYourPlugin: def test_plugin_initialization(self): """Test plugin initialization.""" plugin = YourPlugin() assert plugin.get_name() == "your_platform" assert plugin.get_platform() == "your_platform"

def test_message_handling(self): """Test message handling.""" plugin = YourPlugin()

Test message handling logic

pass


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


📚 Documentation
Documentation Standards
Clear and Concise: Write clear, easy-to-understand documentation
Examples: Provide practical examples
Up-to-Date: Keep documentation current with code changes
Comprehensive: Cover all aspects of the feature
Documentation Types
API Documentation: Document all API endpoints and parameters
User Guides: Step-by-step guides for users
Developer Guides: Technical documentation for developers
Examples: Code examples and use cases
Writing Documentation

# Your Feature

Brief description of the feature.

## Usage

python
from your_module import YourClass

instance = YourClass()
result = instance.method()

Your Feature

Brief description of the feature.

Usage

import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)

from your_module import YourClass

instance = YourClass() result = instance.method()


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


Parameters

param1: Description of parameter 1
param2: Description of parameter 2


Examples
Basic Usage
import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)
Basic example
instance = YourClass() result = instance.method("example")


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

Advanced Usage

import pytest
from your_module import YourClass

class TestYourClass:
    def test_basic_functionality(self):
        """Test basic functionality."""
        instance = YourClass()
        result = instance.method()
        assert result == expected_value
    
    def test_error_handling(self):
        """Test error handling."""
        instance = YourClass()
        with pytest.raises(ValueError):
            instance.method(invalid_input)

Advanced example

instance = YourClass() result = instance.method("example", advanced=True)


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

🐛 Bug Reports

Reporting Bugs

When reporting bugs, include:

Bug Description: Clear description of the bug
Steps to Reproduce: Detailed steps to reproduce the issue
Expected Behavior: What you expected to happen
Actual Behavior: What actually happened
Environment: System information and versions
Logs: Relevant log entries and error messages

Bug Report Template

# Your Feature

Brief description of the feature.

## Usage

python
from your_module import YourClass

instance = YourClass()
result = instance.method()


Bug Description
Brief description of the bug.
Steps to Reproduce
Step 1
Step 2
Step 3
Expected Behavior
What you expected to happen.
Actual Behavior
What actually happened.
Environment
OS: [e.g., Ubuntu 20.04]
Python Version: [e.g., 3.9.0]
SanctumOS Version: [e.g., 0.1.0]
Logs


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

Relevant log entries here


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

✨ Feature Requests

Requesting Features

When requesting features, include:

Feature Description: Clear description of the feature
Use Case: Why this feature is needed
Proposed Solution: How you think it should work
Alternatives: Alternative solutions you've considered
Additional Context: Any additional context or information

Feature Request Template

# Your Feature

Brief description of the feature.

## Usage

python
from your_module import YourClass

instance = YourClass()
result = instance.method()


Feature Description
Brief description of the feature.
Use Case
Why this feature is needed and how it would be used.
Proposed Solution
How you think the feature should work.
Alternatives
Alternative solutions you've considered.
Additional Context
Any additional context or information.


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

🔒 Security

Security Considerations

Input Validation: Validate all inputs
Authentication: Implement proper authentication
Authorization: Implement proper authorization
Data Protection: Protect sensitive data
Error Handling: Don't expose sensitive information in errors

Reporting Security Issues

For security issues, please:

Don't create public issues: Security issues should be reported privately
Email security team: Send details to security@sanctumos.org
Include details: Provide detailed information about the issue
Wait for response: Wait for the security team to respond

📋 Pull Request Process

Before Submitting

Test Your Changes: Ensure all tests pass
Update Documentation: Update relevant documentation
Check Code Quality: Run linting and type checking
Review Changes: Review your changes before submitting

Pull Request Template

# Your Feature

Brief description of the feature.

## Usage

python
from your_module import YourClass

instance = YourClass()
result = instance.method()


Description
Brief description of the changes.
Type of Change
[ ] Bug fix
[ ] New feature
[ ] Breaking change
[ ] Documentation update
Testing
[ ] Tests pass locally
[ ] New tests added for new functionality
[ ] Manual testing completed
Checklist
[ ] Code follows style guidelines
[ ] Self-review completed
[ ] Documentation updated
[ ] No breaking changes (or breaking changes documented)


### Development Workflow

1. Create Feature Branch:
   bash
   git checkout -b feature/your-feature-name

Review Process

Automated Checks: CI/CD pipeline runs tests and checks
Code Review: Maintainers review the code
Testing: Changes are tested in different environments
Approval: Changes are approved and merged

🏆 Recognition

Contributors

Contributors are recognized in:

README: Listed in the contributors section
Release Notes: Mentioned in release notes
Documentation: Credited in relevant documentation
Community: Recognized in the community

Contributor Levels

Contributor: Any contribution to the project
Maintainer: Regular contributor with commit access
Core Team: Core team member with project responsibilities

📞 Getting Help

Development Help

Documentation: Check the documentation first
Issues: Search existing issues for similar problems
Discussions: Join community discussions
Mentorship: Ask for mentorship from experienced contributors

Community

GitHub Discussions: Join discussions on GitHub
Discord: Join the Discord community
Forums: Participate in community forums
Events: Attend community events and meetups

📄 License

By contributing to SanctumOS, you agree that your contributions will be licensed under the same license as the project:

Code: GNU Affero General Public License v3.0 (AGPLv3)
Documentation: Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA 4.0)

Thank you for contributing to SanctumOS! Your contributions help make the AI agent communication platform better for everyone.