# Contributing to DMARQ First off, thank you for considering contributing to DMARQ! It's people like you that make DMARQ such a great tool for DMARC monitoring and email security. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Development Setup](#development-setup) - [Making Changes](#making-changes) - [Testing](#testing) - [Style Guidelines](#style-guidelines) - [Commit Messages](#commit-messages) - [Pull Request Process](#pull-request-process) - [Security](#security) ## Code of Conduct This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. ## How Can I Contribute? ### Reporting Bugs Before creating bug reports, please check the existing issues list as you might find that you don't need to create one. When you are creating a bug report, please include as many details as possible: - **Use a clear and descriptive title** - **Describe the exact steps to reproduce the problem** - **Provide specific examples** to demonstrate the steps - **Describe the behavior you observed** and what you expected - **Include screenshots** if relevant - **Include your environment details** (OS, Python version, Docker version) ### Suggesting Enhancements Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: - **Use a clear and descriptive title** - **Provide a detailed description** of the proposed feature - **Explain why this enhancement would be useful** - **List some examples** of how it would be used - **Consider the scope** - does it fit DMARQ's mission? ### Your First Code Contribution Unsure where to begin? You can start by looking through issues tagged with: - `good first issue` - should only require a few lines of code - `help wanted` - more involved but not requiring deep knowledge of the codebase - `documentation` - improvements or additions to documentation ### Pull Requests - Fill in the required template - Follow the [style guidelines](#style-guidelines) - Include tests when adding features - Update documentation as needed - End all files with a newline ## Development Setup ### Prerequisites - Python 3.13 or higher - Docker and Docker Compose (for full stack testing) - Git ### Local Development Setup 1. **Fork and clone the repository** ```bash git clone https://github.com/YOUR_USERNAME/dmarq.git cd dmarq ``` 2. **Set up Python virtual environment** ```bash cd backend python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt pip install -r requirements-dev.txt # Development dependencies ``` 3. **Set up environment variables** ```bash cp .env.example .env # Edit .env with your local configuration ``` 4. **Run the development server** ```bash cd backend uvicorn app.main:app --reload --port 8080 ``` 5. **Access the application** Open your browser to http://localhost:8080 ### Docker Development For a full stack with database: ```bash docker compose up --build ``` ## Making Changes ### Branch Naming Convention Use descriptive branch names: - `feature/add-new-chart-type` - `fix/imap-connection-error` - `docs/update-api-documentation` - `security/fix-xss-vulnerability` ### Development Workflow 1. **Create a new branch** ```bash git checkout -b feature/your-feature-name ``` 2. **Make your changes** - Write clear, concise code - Follow the style guidelines - Add tests for new functionality - Update documentation 3. **Test your changes** ```bash # Run unit tests pytest # Run with coverage pytest --cov=app --cov-report=html # Run linting pylint app/ flake8 app/ black --check app/ # Run security checks bandit -r app/ safety check ``` 4. **Commit your changes** ```bash git add . git commit -m "feat: add new feature" ``` 5. **Push to your fork** ```bash git push origin feature/your-feature-name ``` 6. **Create a Pull Request** ## Testing ### Running Tests ```bash # Run all tests pytest # Run specific test file pytest backend/app/tests/test_dmarc_parser.py # Run with verbose output pytest -v # Run with coverage report pytest --cov=app --cov-report=term-missing ``` ### Writing Tests - Place tests in `backend/app/tests/` - Name test files with `test_` prefix - Name test functions with `test_` prefix - Use descriptive test names that explain what is being tested Example: ```python def test_dmarc_parser_handles_valid_xml(): """Test that the parser correctly processes valid DMARC XML""" parser = DMARCParser() result = parser.parse_xml(valid_xml_content) assert result is not None assert result['domain'] == 'example.com' ``` ### Test Coverage Goals - Aim for at least 80% code coverage - Critical security features should have 100% coverage - All new features must include tests ## Style Guidelines ### Python Style Guide We follow PEP 8 with some modifications: - **Line length**: Maximum 100 characters (not 79) - **Imports**: Organize as stdlib, third-party, local - **Docstrings**: Use Google-style docstrings - **Type hints**: Use type hints for function signatures Example: ```python from typing import Optional, List from datetime import datetime def process_dmarc_report( domain: str, report_xml: str, timestamp: Optional[datetime] = None ) -> List[dict]: """ Process a DMARC aggregate report. Args: domain: The domain name being reported on report_xml: Raw XML content of the DMARC report timestamp: Optional timestamp for the report Returns: List of processed report records Raises: ValueError: If the XML is malformed """ # Implementation here pass ``` ### Code Formatting We use automated code formatters: ```bash # Format code with black black backend/app/ # Sort imports with isort isort backend/app/ # Type checking with mypy (coming soon) mypy backend/app/ ``` ### Documentation Style - Use clear, concise language - Include code examples where helpful - Keep documentation up-to-date with code changes - Use proper Markdown formatting ## Commit Messages Follow the Conventional Commits specification: ### Format ``` ():