Skip to content

Contributing Guide

Jump to bottom
milad edited this page May 10, 2026 · 1 revision

Thank you for your interest in contributing to the SIR Epidemic Simulator!

📋 Table of Contents

📜 Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

By participating, you agree to uphold this code.

🚀 Getting Started

Prerequisites

Tool Version Check Command
Python 3.8+ python --version
Git Latest git --version
pip Latest pip --version

Fork & Clone

  1. Fork the repository on GitHub
  2. Clone your fork:
git clone https://github.com/YOUR_USERNAME/sir_simulator.git
cd sir_simulator
  1. Add upstream remote:
git remote add upstream https://github.com/miladrezanezhad/sir_simulator.git

🔧 Development Setup

1. Create Virtual Environment

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

2. Install Dependencies

# Install package in development mode
pip install -e .

# Install development dependencies
pip install -r requirements_dev.txt

3. Install Pre-commit Hooks

pre-commit install

4. Verify Setup

# Run all tests
python run_all_tests.py

# Run security tests
python -m unittest discover tests/security

# Check code style
black --check .
flake8 .

📝 Code Guidelines

Python Style

We follow PEP 8 with some modifications:

Tool Configuration
Black Line length: 88
isort Profile: black
flake8 Max line length: 88, ignore: E203, W503
mypy Type checking enabled

Formatting

# Auto-format code
black .
isort .

# Check formatting without changing
black --check .
isort --check-only .

Type Hints

Always include type hints:

# Good
def run_simulation(beta: float, gamma: float, days: int) -> pd.DataFrame:
    pass

# Bad
def run_simulation(beta, gamma, days):
    pass

Docstrings

Use Google-style docstrings:

def function_name(param1: str, param2: int) -> bool:
    """
    Brief description of function.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: When param1 is invalid

    Examples:
        >>> function_name("test", 42)
        True
    """
    pass

Naming Conventions

Type Convention Example
Variables snake_case infected_count
Functions snake_case run_simulation()
Classes PascalCase SocialNetworkSimulator
Constants UPPER_SNAKE MAX_POPULATION
Private _leading_underscore _internal_method()

Imports Order

# 1. Standard library
import json
import os
from typing import List

# 2. Third-party
import numpy as np
import pandas as pd

# 3. Local
from sir_simulator.core_models.sir_model import run_sir_simulation

🧪 Testing Guidelines

When to Write Tests

  • ✅ All new features
  • ✅ Bug fixes
  • ✅ Refactoring
  • ❌ Documentation changes
  • ❌ Configuration changes

Test Structure (AAA Pattern)

def test_something():
    # Arrange - Set up test data
    input_data = create_test_data()
    
    # Act - Execute the code
    result = function_to_test(input_data)
    
    # Assert - Verify the result
    self.assertEqual(result, expected)

Test Naming

# Good - describes behavior
def test_run_sir_returns_dataframe():
    pass

def test_calculate_peak_infected_correctly():
    pass

# Bad - vague
def test_sir():
    pass

def test_function():
    pass

Run Tests Locally

# Run all tests
python run_all_tests.py

# Run specific test file
python tests/test_seir.py

# Run security tests
python -m unittest discover tests/security

# Run with coverage
coverage run --source=src/sir_simulator -m unittest discover tests
coverage report
coverage html

Writing New Tests

Add to existing file or create new one:

import unittest
from sir_simulator.your_module import your_function

class TestYourFeature(unittest.TestCase):
    
    def test_normal_case(self):
        result = your_function(valid_input)
        self.assertEqual(result, expected)
    
    def test_edge_case(self):
        result = your_function(empty_input)
        self.assertEqual(result, expected)
    
    def test_error_case(self):
        with self.assertRaises(ValueError):
            your_function(invalid_input)

if __name__ == '__main__':
    unittest.main()

📚 Documentation Guidelines

Where to Update

Change Type Update
New feature README.md, tutorials, API reference
Bug fix CHANGELOG.md
API change API reference, docstrings
Configuration README.md

Docstring Checklist

  • Brief description
  • Args section (type and description)
  • Returns section (type and description)
  • Raises section (if applicable)
  • Examples section (if useful)

README Updates

When adding features, update relevant sections:

  • Installation
  • Quick Start
  • Usage Guide
  • Project Structure

🔄 Pull Request Process

Before Submitting

  1. Update your fork:
git checkout main
git pull upstream main
git push origin main
  1. Create a branch:
git checkout -b feature/your-feature-name
  1. Make changes and commit:
git add .
git commit -m "feat: add your feature description"
  1. Run tests:
python run_all_tests.py
python -m unittest discover tests/security
  1. Push and create PR:
git push origin feature/your-feature-name

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code refactor
  • test: Tests
  • chore: Maintenance

Examples:

feat(network): add small-world network generator

fix(optimization): handle edge case when beta is zero

docs(readme): update installation instructions

test(seir): add population conservation test

PR Template

Fill out the PR template completely:

  • Description of changes
  • Type of change
  • Testing performed
  • Checklist completed

PR Review Process

  1. CI checks must pass
  2. At least one review required
  3. Address feedback with additional commits
  4. Squash commits when approved
  5. Merge (maintainer will do)

🐛 Reporting Issues

Bug Report Template

## Bug Description
[Clear description]

## Steps to Reproduce
1. Run command...
2. Enter parameters...
3. See error

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- OS: [Windows/Linux/Mac]
- Python Version: [e.g., 3.10]
- Package Version: [e.g., 1.0.0]

## Additional Context
[Screenshots, logs, etc.]

Issue Labels

Label Meaning
bug Verified bug
enhancement Feature request
documentation Docs issue
good-first-issue Beginner friendly
help-wanted Need assistance
question Support request

💡 Feature Requests

Feature Request Template

## Problem Statement
[What problem does this solve?]

## Proposed Solution
[How should it work?]

## Alternative Solutions
[Other approaches considered]

## Use Case
[Who would benefit?]

## Additional Context
[References, examples, etc.]

✅ Review Checklist

Code Review

  • Code follows style guidelines
  • Type hints included
  • Docstrings added
  • Tests written and passing
  • No new warnings
  • CHANGELOG updated

Documentation Review

  • README updated (if needed)
  • Tutorials updated (if needed)
  • API reference updated (if needed)
  • Examples work correctly

Security Review

  • No hardcoded secrets
  • Input validation added
  • Security tests pass
  • No new vulnerabilities

🎯 First-Time Contributors

Good First Issues

Look for issues labeled good-first-issue:

  • Small, self-contained changes
  • Clear requirements
  • Mentorship available

Steps

  1. Comment on the issue: "I'd like to work on this"
  2. Follow the PR process
  3. Ask questions if stuck

Getting Help

Channel Use for
Issue comments Specific issue discussion
GitHub Discussions General questions
Email Security or private matters

📊 Recognition

Contributors

All contributors will be added to the CONTRIBUTORS.md file (coming soon).

Acknowledgments

Significant contributions will be mentioned in the CHANGELOG and README.

🔗 Useful Links

Thank you for contributing! 🙏

⬆ Back to Home

🦠 SIR Epidemic Simulator

📚 Main Pages

📖 Tutorials

📚 Reference

🔗 External Links

  • GitHub
  • PyPI
  • Issues

📊 Badges

Tests Security

Need help?
Open an issue

Clone this wiki locally