Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
289 lines (214 loc) · 7.7 KB

CONTRIBUTING.md

File metadata and controls

289 lines (214 loc) · 7.7 KB

Contributing to Apple Mail MCP Server

Thank you for your interest in contributing to the Apple Mail MCP Server! This document provides guidelines and instructions for contributing to this project.

Table of Contents

Getting Started

Contributions are welcome! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help is appreciated.

Prerequisites

Before contributing, ensure you have:

  • macOS (required for development and testing)
  • Go 1.21 or later
  • Apple Mail.app installed and configured
  • Git
  • Basic familiarity with Go and AppleScript

Development Setup

  1. Fork and clone the repository:

    git clone https://github.com/YOUR_USERNAME/apple-mail-mcp.git
cd apple-mail-mcp

  2. Install dependencies:

    go mod download

  3. Build the project:

    make build

  4. Run tests to ensure everything works:

    make test

How to Contribute

Types of Contributions

We welcome various types of contributions:

  • Bug fixes: Fix issues and improve stability
  • New features: Add new tools or enhance existing ones
  • Documentation: Improve README, technical docs, or code comments
  • Tests: Add test coverage or improve existing tests
  • Performance: Optimize code or reduce resource usage
  • Code quality: Refactoring, cleanup, or following best practices

Contribution Workflow

  1. Fork the repository on GitHub

  2. Create a feature branch from main:

    git checkout -b feature/your-feature-name

    or

    git checkout -b fix/your-bug-fix

  3. Make your changes following the code standards below

  4. Write or update tests for your changes

  5. Run tests and quality checks:

    make test
make check

  6. Commit your changes with clear, descriptive messages:

    git commit -m "Add feature: description of what you added"

  7. Push to your fork:

    git push origin feature/your-feature-name

  8. Open a Pull Request on GitHub with:

    • Clear title and description
    • Reference to any related issues
    • Description of changes and why they're needed
    • Test results and any manual testing performed

Code Standards

Go Code Conventions

Follow standard Go conventions and best practices:

  • Formatting: Use gofmt or make fmt to format code
  • Naming: Use idiomatic Go naming conventions
    • Exported names: CamelCase
    • Unexported names: camelCase
    • Acronyms: HTTPServer, not HttpServer
  • Comments:
    • Document all exported functions, types, and constants
    • Use complete sentences with proper punctuation
    • Start with the name being documented
  • Error handling: Always check and handle errors appropriately
  • Package organization: Keep related functionality together

Code Quality

  • Linting: Code must pass golangci-lint checks 
    make lint
  • Simplicity: Prefer clear, simple code over clever solutions
  • Avoid premature optimization: Focus on correctness first
  • Security: Always validate and sanitize inputs
  • Logging: Use appropriate log levels (DEBUG, INFO, ERROR)

Project-Specific Guidelines

  • AppleScript security: Always escape and validate parameters before executing AppleScript
  • Input validation: Use the security package for all external inputs
  • Error types: Use or extend existing error types from internal/models/errors.go
  • Tool handlers: Follow the pattern established in internal/mail/connector.go

Testing Requirements

All contributions must include appropriate tests:

Test Coverage

  • Target coverage: Aim for good test coverage for new code, especially in security-critical areas
  • Current status: Security and utility packages have test coverage; contributions to expand test coverage are welcome
  • Check coverage: 
    make test-coverage
make coverage-html  # View in browser

Writing Tests

  • Unit tests: Test individual functions and methods

    • Place tests in *_test.go files alongside source
    • Use table-driven tests for multiple test cases
    • Mock external dependencies (AppleScript, file system)

  • Test naming: Use descriptive names

    func TestValidateEmail_ValidAddress_ReturnsTrue(t *testing.T) { ... }
func TestValidateEmail_InvalidFormat_ReturnsError(t *testing.T) { ... }

  • Test structure: Follow Arrange-Act-Assert pattern

    // Arrange: Setup test data and conditions
email := "test@example.com"

// Act: Execute the function being tested
result := ValidateEmail(email)

// Assert: Verify the results
assert.True(t, result)

Running Tests

# Run all tests
make test

# Run specific package tests
go test ./internal/security/...

# Run with race detection
go test -race ./...

# Run specific test
go test -run TestValidateEmail ./pkg/utils/

Pull Request Process

Before Submitting

  • Code follows Go conventions and project guidelines
  • All tests pass: make test
  • Code is formatted: make fmt
  • Linter passes: make lint (if available)
  • Tests added for new functionality (especially security-critical code)
  • Documentation is updated (README, TECHNICAL.md, code comments)
  • Commit messages are clear and descriptive

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Changes Made
- List of specific changes

## Testing
- How you tested the changes
- Test coverage results

## Related Issues
Fixes #(issue number)

## Checklist
- [ ] Tests pass
- [ ] Code is formatted
- [ ] Documentation updated

Review Process

  1. A maintainer will review your PR
  2. Address any requested changes
  3. Once approved, a maintainer will merge your PR
  4. Your contribution will be included in the next release

Reporting Issues

Bug Reports

When reporting bugs, please include:

  • Description: Clear description of the issue
  • Environment:
    • macOS version
    • Go version
    • Mail.app version
    • Server version
  • Steps to reproduce: Detailed steps to reproduce the issue
  • Expected behavior: What you expected to happen
  • Actual behavior: What actually happened
  • Logs: Relevant error messages or debug logs
  • Additional context: Screenshots, configuration, etc.

Feature Requests

For feature requests, please describe:

  • Use case: Why this feature is needed
  • Proposed solution: How you envision it working
  • Alternatives considered: Other approaches you've thought about
  • Impact: Who would benefit from this feature

Getting Help

If you need help with your contribution:

  1. Check the README and TECHNICAL.md
  2. Review the Troubleshooting Guide
  3. Look at existing code and tests for examples
  4. Open a GitHub issue with the question label
  5. Describe what you're trying to do and where you're stuck

Code of Conduct

Be respectful, constructive, and professional in all interactions. We aim to maintain a welcoming and inclusive environment for all contributors.

License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Apple Mail MCP Server! 🎉