Contributing to MIESC

July 12, 2026 · View on GitHub

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

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

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to fboiero@frvm.utn.edu.ar.

Getting Started

Prerequisites

Python 3.12 or higher
Git
Virtual environment (recommended)
Solidity compiler (solc) for testing

Quick Setup

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/MIESC.git
cd MIESC

# 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

# Run tests to verify setup
pytest tests/

How to Contribute

Types of Contributions

Type	Description	Label
Bug Fix	Fix a bug in existing code	`bug`
Feature	Add new functionality	`enhancement`
Documentation	Improve or add documentation	`documentation`
Testing	Add or improve tests	`testing`
Refactoring	Code improvements without changing behavior	`refactor`
Translation	Add language translations	`i18n`

Finding Issues

Look for issues labeled good first issue
Check help wanted for priority items
Review the project roadmap

Proposing Changes

Check existing issues to avoid duplicates
Open an issue to discuss significant changes before coding
Get feedback from maintainers on your approach

Development Setup

Environment Configuration

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate

# Install all dependencies (including dev)
pip install -r requirements.txt
pip install -r requirements_dev.txt

# Install pre-commit hooks
pre-commit install

# Verify installation
python scripts/verify_installation.py

Required Tools

Tool	Purpose	Installation
pytest	Testing	`pip install pytest pytest-cov`
black	Code formatting	`pip install black`
ruff	Linting	`pip install ruff`
mypy	Type checking	`pip install mypy`
pre-commit	Git hooks	`pip install pre-commit`

Project Structure

MIESC/
├── src/                    # Main source code
│   ├── adapters/          # Tool adapters
│   ├── core/              # Core framework
│   ├── ml/                # Machine learning components
│   └── mcp/               # MCP protocol implementation
├── tests/                  # Test suite
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── fixtures/          # Test data
├── docs/                   # Documentation
├── examples/               # Example scripts
└── contracts/              # Test contracts

Coding Standards

Python Style Guide

We follow PEP 8 with these additions:

Rule	Setting
Line length	100 characters max
Formatter	Black
Import sorting	isort
Docstrings	Google style

Code Formatting

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
ruff check src/ tests/

# Type check
mypy src/

Example Code Style

"""Module docstring describing purpose.

This module provides functionality for...
"""

from typing import Dict, List, Optional

from miesc.core import BaseAdapter


class MyAdapter(BaseAdapter):
    """Adapter for MyTool security scanner.

    This adapter wraps the MyTool CLI and normalizes
    its output to the MIESC finding format.

    Attributes:
        name: Tool identifier.
        category: Tool category (STATIC, DYNAMIC, etc.).
    """

    def __init__(self, config: Optional[Dict] = None) -> None:
        """Initialize the adapter.

        Args:
            config: Optional configuration dictionary.
        """
        super().__init__(config)
        self.name = "mytool"
        self.category = "STATIC"

    def analyze(self, contract_path: str, timeout: int = 300) -> Dict:
        """Analyze a smart contract.

        Args:
            contract_path: Path to the Solidity file.
            timeout: Maximum execution time in seconds.

        Returns:
            Dictionary containing analysis results with keys:
                - status: "success" or "error"
                - findings: List of vulnerability findings
                - metadata: Execution metadata

        Raises:
            FileNotFoundError: If contract file doesn't exist.
            TimeoutError: If analysis exceeds timeout.
        """
        # Implementation
        pass

Testing

For comprehensive testing documentation, see Testing Guide.

Quick Reference

# Run all tests with coverage
make test

# Run tests without coverage (faster)
make test-quick

# Run only integration tests
pytest -m integration --no-cov

# Run specific test file
pytest tests/test_integration_pipeline.py -v --no-cov

Writing Tests

"""Tests for SlitherAdapter."""

import pytest
from miesc.adapters.slither_adapter import SlitherAdapter


class TestSlitherAdapter:
    """Test suite for SlitherAdapter."""

    @pytest.fixture
    def adapter(self):
        """Create adapter instance for tests."""
        return SlitherAdapter()

    @pytest.fixture
    def sample_contract(self, tmp_path):
        """Create a sample contract for testing."""
        contract = tmp_path / "test.sol"
        contract.write_text("""
            pragma solidity ^0.8.0;
            contract Test {
                function foo() public {}
            }
        """)
        return str(contract)

    def test_analyze_valid_contract(self, adapter, sample_contract):
        """Test analysis of a valid contract."""
        result = adapter.analyze(sample_contract)

        assert result["status"] == "success"
        assert "findings" in result
        assert isinstance(result["findings"], list)

    def test_analyze_invalid_path(self, adapter):
        """Test analysis with invalid file path."""
        with pytest.raises(FileNotFoundError):
            adapter.analyze("/nonexistent/path.sol")

Test Coverage Requirements

Minimum coverage: 80%
New features must include tests
Bug fixes must include regression tests

Mutation Testing (Optional)

We use mutmut for mutation testing to validate test quality:

# Quick mutation test (core modules)
make mutate-quick

# Full mutation analysis
make mutate

# View results
make mutate-results

For detailed instructions, see Mutation Testing Guide.

Pull Request Process

Before Submitting

Create a branch

git checkout -b feature/your-feature-name

Make your changes
- Follow coding standards
- Add/update tests
- Update documentation

Run checks locally

# Format code
black src/ tests/

# Run linter
ruff check src/ tests/

# Run tests
pytest tests/

# Check types
mypy src/

Commit with clear messages

git commit -m "feat: add support for new tool X

- Implement XAdapter class
- Add unit tests for X integration
- Update documentation

Closes #123"

Commit Message Format

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation
style: Formatting
refactor: Code restructuring
test: Adding tests
chore: Maintenance

Signed Commits (Optional but Recommended)

We encourage signing your commits with GPG for added security and verification:

# Configure Git for signed commits
git config --global commit.gpgsign true
git config --global user.signingkey YOUR_KEY_ID

Signed commits show as "Verified" on GitHub and provide:

Authenticity: Proves you authored the commit
Integrity: Confirms the commit hasn't been modified
Trust: Shows verification badge on GitHub

For detailed setup instructions, see Signed Commits Guide.

Submitting the PR

Push your branch

git push origin feature/your-feature-name

Create Pull Request on GitHub
Fill out the PR template:
- Description of changes
- Related issue(s)
- Testing performed
- Documentation updates
Request review from maintainers

PR Review Checklist

Code follows style guidelines
Tests pass and coverage maintained
Documentation updated
No security vulnerabilities introduced
Commit messages follow convention
PR description is complete

Documentation

Types of Documentation

Type	Location	Format
Code docs	In source files	Docstrings
User guide	`docs/`	Markdown
API reference	`docs/api/`	Auto-generated
Examples	`examples/`	Python scripts

Building Documentation

# Install documentation dependencies
pip install mkdocs mkdocs-material mkdocs-minify-plugin

# Serve docs locally
mkdocs serve -f docs/mkdocs.yml

# Build static site
mkdocs build -f docs/mkdocs.yml