Contributing to Houdinis Framework

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

Code of Conduct
Getting Started
Development Environment
How to Contribute
Coding Standards
Testing
Pull Request Process
Security
Community

Code of Conduct

This project adheres to a Code of Conduct that all contributors are expected to follow. Please read CODE_OF_CONDUCT.md before contributing.

Getting Started

Prerequisites

Python 3.10 or higher
Docker and Docker Compose
Git
Basic understanding of quantum computing concepts
Familiarity with cryptography

Fork and Clone

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/Houdinis.git
cd Houdinis

Add the upstream repository:

git remote add upstream https://github.com/maurorisonho/Houdinis.git

Development Environment

Setup Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install pytest pytest-cov black isort mypy bandit

Configure Pre-commit Hooks

# Install pre-commit
pip install pre-commit

# Setup hooks
pre-commit install

Docker Development

# Build Docker images
cd docker
docker-compose build

# Run containers
docker-compose up -d

# Access the framework
docker exec -it houdinis_framework bash

How to Contribute

Types of Contributions

We welcome various types of contributions:

Bug Reports - Report issues you encounter
Feature Requests - Suggest new features or improvements
Code Contributions - Fix bugs or implement features
Documentation - Improve docs, add examples, write tutorials
Testing - Write tests, improve test coverage
Quantum Algorithms - Implement new quantum algorithms
Cryptanalysis Modules - Add new exploit modules

Reporting Bugs

Before creating a bug report:

Check existing issues to avoid duplicates
Collect relevant information (OS, Python version, error messages)

Use the bug report template when creating an issue:

Clear, descriptive title
Steps to reproduce
Expected vs actual behavior
Environment details
Logs or screenshots if applicable

Suggesting Features

When suggesting features:

Check if feature already exists or is planned
Describe the problem it solves
Explain the proposed solution
Consider implementation complexity
Discuss alternatives

Coding Standards

Python Style Guide

We follow PEP 8 with some modifications:

# Maximum line length: 100 characters
# Use 4 spaces for indentation (no tabs)
# Use double quotes for strings
# Use type hints for function signatures

def example_function(param: str, value: int = 10) -> bool:
    """
    Brief description of function.
    
    Args:
        param: Description of param
        value: Description of value with default
    
    Returns:
        Description of return value
    """
    return True

Code Formatting

# Format code with Black
black .

# Sort imports with isort
isort .

# Type checking with Pyright
pyright .

Naming Conventions

Classes: PascalCase (QuantumModule, RSAShor)
Functions/Methods: snake_case (calculate_phase, run_exploit)
Constants: UPPER_SNAKE_CASE (MAX_QUBITS, DEFAULT_BACKEND)
Private members: Prefix with underscore (_internal_method)

Documentation

All public APIs must include docstrings:

class QuantumExploit:
    """
    Base class for quantum cryptanalysis exploits.
    
    This class provides the foundation for implementing quantum algorithms
    that can be used to break classical cryptographic systems.
    
    Attributes:
        backend: Quantum backend to use for execution
        qubits: Number of qubits required
    
    Example:
        >>> exploit = QuantumExploit(backend='ibm_quantum')
        >>> result = exploit.run(target='192.168.1.1')
    """

Testing

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/unit/test_cli.py

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

# Run only unit tests
pytest tests/unit/ -v

# Run integration tests (slower)
pytest tests/integration/ -v

Writing Tests

All new code should include tests:

# tests/unit/test_new_feature.py
import pytest
from your_module import YourClass

class TestYourClass:
    """Test suite for YourClass"""
    
    @pytest.fixture
    def instance(self):
        """Create instance for testing"""
        return YourClass()
    
    def test_basic_functionality(self, instance):
        """Test basic functionality"""
        result = instance.method()
        assert result == expected_value
    
    @pytest.mark.security
    def test_security_validation(self, instance):
        """Test security features"""
        # Test security-related functionality
        pass

Test Coverage Requirements

Unit tests: Minimum 60% coverage
Integration tests: Major user flows
Security tests: All security-critical code
Edge cases: Boundary conditions, error handling

Pull Request Process

Before Submitting

Create a branch:

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

Make your changes:
- Follow coding standards
- Add tests
- Update documentation
- Run tests locally

Commit your changes:

git add .
git commit -m "feat: Add quantum Grover optimizer

- Implement optimized Grover's algorithm
- Add benchmarks for different input sizes
- Update documentation with usage examples"

Commit Message Convention

We follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Adding or updating tests
refactor: Code refactoring
perf: Performance improvements
security: Security fixes
ci: CI/CD changes

Submitting Pull Request

Push to your fork:

git push origin feature/your-feature-name

Create Pull Request on GitHub:
- Use a clear, descriptive title
- Fill out the PR template completely
- Link related issues
- Add screenshots/demos if applicable
- Request reviews from maintainers
Address review feedback:
- Respond to comments
- Make requested changes
- Push updates to your branch
Merge requirements:
- All tests pass
- Code coverage maintained/improved
- Security scans pass
- At least one approval from maintainer
- No merge conflicts

Security

Responsible Disclosure

DO NOT open public issues for security vulnerabilities!

Instead:

Use GitHub Security Advisories (private reporting)
Provide detailed description
Include proof of concept if possible
Wait for response before public disclosure

Security Considerations

When contributing:

Never commit secrets, API keys, or credentials
Validate all user inputs
Use secure coding practices
Follow OWASP guidelines
Test for common vulnerabilities

Community

Getting Help

Documentation: Read the docs/ directory
Discussions: GitHub Discussions for questions
Discord: Join our Discord server (link in README)
Email: houdinis@example.com

Recognition

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation
Special mentions for significant contributions

Areas Needing Help

Check issues labeled:

good first issue - Great for newcomers
help wanted - Need community assistance
documentation - Docs improvements needed
testing - Test coverage needed
enhancement - Feature implementations

Development Workflow

1. Pick an Issue

Browse open issues
Comment to claim an issue
Ask for clarification if needed

2. Develop

Create feature branch
Write code and tests
Run local tests
Update documentation

3. Submit

Push changes
Create pull request
Respond to feedback
Iterate until approved

4. Celebrate

Your contribution is merged!
Thank you for making Houdinis better!

Additional Resources

Questions?

Don't hesitate to ask! We're here to help.

Thank you for contributing to Houdinis Framework!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History