gh-christianlouis-dmarq/CONTRIBUTING.md

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
• How Can I Contribute?
• Development Setup
• Making Changes
• Testing
• Style Guidelines
• Commit Messages
• Pull Request Process
• 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
• 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

git clone https://github.com/YOUR_USERNAME/dmarq.git
cd dmarq

2. Set up Python virtual environment

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

cp .env.example .env
# Edit .env with your local configuration

4. Run the development server

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:

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

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

# 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

git add .
git commit -m "feat: add new feature"

5. Push to your fork

git push origin feature/your-feature-name

6. Create a Pull Request

Testing

Running Tests

# 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:

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:

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:

# 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

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

<body>

<footer>

Types

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Code style changes (formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Performance improvements
• test: Adding missing tests or correcting existing tests
• chore: Changes to build process or auxiliary tools
• security: Security improvements or fixes

Examples

feat(parser): add support for forensic DMARC reports

Added parsing logic for DMARC forensic (failure) reports (RUF).
This allows users to see detailed information about individual
email authentication failures.

Closes #123

fix(imap): handle connection timeout gracefully

The IMAP client now properly handles timeout exceptions and
retries with exponential backoff. This prevents the application
from crashing when the mail server is temporarily unavailable.

Fixes #456

security(api): add authentication to admin endpoints

Added authentication checks to /api/v1/admin/* endpoints to
prevent unauthorized access.

BREAKING CHANGE: Admin endpoints now require authentication token

Pull Request Process

Before Submitting

1. Ensure your code follows the style guidelines
2. Run all tests and ensure they pass
3. Update documentation as necessary
4. Add or update tests for your changes
5. Run security scans if touching sensitive code
6. Verify the application works with your changes

PR Template

When you create a PR, fill out the template completely:

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
Describe the tests you ran and how to reproduce them

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

Review Process

1. Automated checks must pass (linting, tests, security scans)
2. At least one maintainer review is required
3. Address review comments promptly and professionally
4. Keep the PR focused - one feature/fix per PR
5. Be patient - maintainers review PRs as time allows

After Approval

Once approved, a maintainer will merge your PR. The merge will trigger:

• Automated deployment (if applicable)
• Documentation updates
• Release notes generation

Security

Reporting Security Issues

DO NOT create public issues for security vulnerabilities. Instead:

1. Email the maintainers (see SECURITY.md for contact info)
2. Provide detailed information about the vulnerability
3. Allow time for the issue to be addressed before public disclosure

Security Best Practices

When contributing code that touches security-sensitive areas:

• Never commit secrets (API keys, passwords, etc.)
• Validate all inputs from users or external systems
• Use parameterized queries (our ORM does this automatically)
• Follow principle of least privilege
• Add security tests for authentication/authorization changes
• Document security implications in your PR

Security Checklist for PRs

If your PR involves any of these, extra scrutiny is required:

• Authentication or authorization
• Data validation or sanitization
• Database queries
• File uploads or downloads
• External API calls
• Cryptography or password handling
• Configuration or environment variables

Working with AI Assistants (Agentic Coding)

DMARQ is designed to be "agentic coding friendly" - meaning it works well with AI coding assistants like GitHub Copilot, Cursor, and similar tools.

Tips for AI-Assisted Development

1. Clear Context: Ensure your AI assistant has context about DMARQ's architecture
2. Security First: Always review AI-generated code for security implications
3. Test Coverage: AI-generated code still needs tests
4. Code Review: Human review is essential for AI-generated contributions
5. Documentation: Update docs even for AI-assisted changes

Prompts that Work Well

When using AI assistants, these patterns work well:

"Add a new API endpoint to [do something], following DMARQ's existing patterns in the api/ directory"

"Write tests for [functionality] using the existing test structure in tests/"

"Refactor [module] to improve [aspect] while maintaining backward compatibility"

"Add input validation for [endpoint] following DMARQ's security guidelines"

Questions?

If you have questions about contributing:

• Check the documentation
• Search existing issues
• Join our community discussions
• Ask in your PR - maintainers are happy to help!

Recognition

Contributors are recognized in:

• The project README
• Release notes
• The contributors page (coming soon)

Thank you for making DMARQ better! 🎉