Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
322 lines (233 loc) · 7.52 KB

CONTRIBUTING.md

File metadata and controls

322 lines (233 loc) · 7.52 KB
Raw

Contributing to FLARE 🔥

First off, thank you for considering contributing to FLARE! It's people like you that make FLARE such a great tool for fire safety and education.

🌟 Ways to Contribute

🐛 Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Bug Report Template:

**Description:**
A clear description of the bug.

**Steps to Reproduce:**
1. Go to '...'
2. Click on '...'
3. See error

**Expected Behavior:**
What you expected to happen.

**Actual Behavior:**
What actually happened.

**Environment:**
- OS: [e.g. Windows 10]
- Python Version: [e.g. 3.9.5]
- OpenCV Version: [e.g. 4.5.3]

**Screenshots:**
If applicable, add screenshots.

💡 Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. Create an issue and provide:

  • Clear title describing the enhancement
  • Detailed description of the proposed functionality
  • Use case explaining why this would be useful
  • Possible implementation if you have ideas

🔧 Pull Requests

  1. Fork the repo and create your branch from main
  2. Write clear code following our style guidelines
  3. Add tests if you're adding functionality
  4. Update documentation for any changed functionality
  5. Follow commit message conventions

Commit Message Format:

type(scope): subject

body

footer

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance tasks

Example:

feat(detection): add confidence scoring to fire detection

- Implemented confidence calculation based on multiple factors
- Added confidence display in UI
- Updated tests

Closes #123

📝 Code Style Guidelines

Python Style Guide

We follow PEP 8 with some additions:

# Good ✅
def detect_fire(frame, threshold=0.5):
    """
    Detect fire in a video frame.
    
    Args:
        frame: Input image in BGR format
        threshold: Detection confidence threshold (0.0 to 1.0)
        
    Returns:
        tuple: (processed_frame, is_fire_detected, confidence)
    """
    # Implementation
    pass

# Bad ❌
def detectFire(frame,threshold=.5):
    # no docstring, inconsistent spacing
    pass

Documentation Style

  • Every function needs a docstring
  • Use clear variable names (descriptive over short)
  • Comment complex logic (explain WHY, not WHAT)
  • Add learning notes for educational code
# Good ✅
# Calculate circularity to filter flame-like shapes
# Flames are irregular: 0.1 < circularity < 0.7
circularity = 4 * np.pi * area / (perimeter ** 2)

# Bad ❌
# Calculate circularity
circularity = 4 * np.pi * area / (perimeter ** 2)

🧪 Testing

Running Tests

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_detection.py

# Run with coverage
python -m pytest --cov=. tests/

Writing Tests

import unittest
from fire_smoke_detector_advanced import DetectionEngine

class TestFireDetection(unittest.TestCase):
    def setUp(self):
        self.engine = DetectionEngine()
        
    def test_fire_detection_with_flame(self):
        """Test that fire is detected in frame with flame"""
        # Load test image with fire
        frame = cv2.imread('tests/fixtures/fire_sample.jpg')
        
        # Run detection
        _, detected, confidence = self.engine.detect_fire(frame)
        
        # Assert
        self.assertTrue(detected)
        self.assertGreater(confidence, 0.5)

📚 Documentation

Adding Documentation

  • Update README.md for user-facing changes
  • Add docstrings for new functions/classes
  • Create tutorial docs in docs/tutorials/ for features
  • Update API reference in docs/api/

Documentation Structure

docs/
├── tutorials/           # Step-by-step guides
│   ├── beginners-guide.md
│   └── algorithms.md
├── api/                # API reference
│   └── reference.md
└── images/            # Screenshots and diagrams

🏗️ Project Structure

flare-fire-detection/
├── fire_smoke_detector_base.py       # Base version
├── fire_smoke_detector_advanced.py   # Advanced version
├── requirements.txt                   # Dependencies
├── tests/                            # Test suite
├── docs/                             # Documentation
├── examples/                         # Example scripts
└── assets/                           # Resources

🎯 Development Workflow

Setting Up Development Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/smoke-spark-fire-detection-ai.git
cd smoke-spark-fire-detection-ai

# Add upstream remote
git remote add upstream https://github.com/Shayanthn/smoke-spark-fire-detection-ai.git

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

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

# Install pre-commit hooks
pre-commit install

Making Changes

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes
# ... edit files ...

# Run tests
python -m pytest

# Commit changes
git add .
git commit -m "feat: add amazing feature"

# Push to your fork
git push origin feature/amazing-feature

# Create Pull Request on GitHub

Keeping Your Fork Updated

# Fetch upstream changes
git fetch upstream

# Merge upstream main into your main
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

🎓 Learning Resources

If you're new to contributing to open source:

💬 Communication

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and general discussion
  • Email: shayanthn78@gmail.com for private matters

🏆 Recognition

Contributors will be:

  • Listed in the README.md contributors section
  • Mentioned in release notes
  • Given credit in documentation

📜 Code of Conduct

Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone, regardless of:

  • Age, body size, disability
  • Ethnicity, gender identity and expression
  • Level of experience, education
  • Nationality, personal appearance, race, religion
  • Sexual identity and orientation

Our Standards

Positive behavior:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints
  • Gracefully accepting constructive criticism
  • Focusing on what's best for the community
  • Showing empathy towards others

Unacceptable behavior:

  • Trolling, insulting/derogatory comments
  • Public or private harassment
  • Publishing others' private information
  • Other conduct inappropriate in professional settings

Enforcement

Violations may be reported to shayanthn78@gmail.com. All complaints will be reviewed and investigated.

❓ Questions?

Don't hesitate to ask! You can:

Thank you for contributing to FLARE! Together we're making the world safer! 🔥

- Shayan Taherkhani