CONTRIBUTING.md

🤝 Contributing to AnalisiOpenData

0		Contributions are welcome! Follow these guidelines:
1		Verify that it has not already been reported, describe the problem with examples
2		Fork, create a branch, make sure tests pass
4		Update documentation
3		Follow PEP8 for Python
5		Process of pull requests
6		Open a discussion for questions or proposals

Thank you for your interest in contributing to AnalisiOpenData! This document provides guidelines for contributing to the project effectively.

---

🐛

Before opening an issue:

1. Check that the bug has not already been reported in existing issues
2. Update to the latest version of the project

How to report:

Open a new issue with the "Bug Report" template and include:

• Clear description of the problem
• Steps to play the bug
• Expected Behavior vs Actual Behavior
• Screenshot or log (if relevant)
• Python Version and Dependencies

---

💡

Before proposing a new feature:

1. Check that it has not already been requested in the issue
2. Open a discussion to propose the idea and receive feedback

How to propose:

Open a new issue with the "Feature Request" template and include:

• Description of the functionality
• Motivation (why is it useful?)
• Possible implementation (if you already have an idea)

---

📐

• Python: Follow for code styling
• Docstring: Use the Google or NumPy format to document functions and classes
• Comments: Write comments in English to explain complex logic
• Names: Use descriptive names for variables and functions (e.g. 'get_dataset_list()')
• Line Length: Maximum 79 characters for code, 72 for comments

Docstring Example:

def analyze_accidents(data: pd.DataFrame) -> dict:
    """
    Analyzes road accident data and returns statistics.

    Args:
        data (pd.DataFrame): DataFrame containing accident data
            with columns: 'latitudine', 'longitudine', 'data'

    Returns:
        dict: Dictionary with 'total_accidents', 'date_range', 'map_html'
    """
    pass

🧪

Before sending a Pull Request:

Run all tests to check for regressions:

cd tests
python run_unified_tests.py

Add tests for new features or fixes:

Tests go to the tests/folder

Follow the format of existing tests

Make sure all tests pass

Specific tests:

python test_config.py      # Configuration
python test_unified.py     # Unit Test
python test_utils.py       # Utility

🔄

Step 1: Fork and Clone

# Repository fork on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/AnalisiOpenData.git
cd AnalysisOpenData

Step 2: Create a Branch

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

Step 3: Make the Changes Follow the Coding Standards

Add tests for new features

Update documentation if necessary

Step 4: Commit and Push

git add.
git commit -m "Clear description of changes"
git push origin feature/feature-name

Step 5: Open the Pull Request

Go to the original repository on GitHub

Click on "Compare & pull request"

Fill in the template:

Description: What you did and why

Linked issue: If it resolves an issue, link it (e.g. "Fixes #123")

Test: Specify which tests you performed

What to expect A maintainer will review the PR within 1-2 weeks

Changes may be required

Once approved, it will be merged into the main branch

Open a Discussion in the GitHub Discussions section, Do not use issues for generic questions

By contributing to this project, you agree that your contributions are distributed under the Apache License 2.0.

Contact the maintainer, for urgent questions

Thank you for your contribution!