Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
238 lines (180 loc) · 4.91 KB

CONTRIBUTING.md

File metadata and controls

238 lines (180 loc) · 4.91 KB

Contributing to mailcli

Thank you for your interest in contributing to mailcli! Contributions are welcome!

Getting Started

Prerequisites

  • Go 1.24 or higher
  • Basic knowledge of Go and IMAP protocol
  • Familiarity with command-line tools

Setting Up Development Environment

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/mailcli.git
cd mailcli

# Add upstream remote
git remote add upstream https://github.com/keepmind9/mailcli.git

# Install dependencies
go mod download

# Run tests to verify setup
make test

Development Workflow

  1. Create a feature branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Write code following the project structure
    • Add tests for new features
    • Update documentation as needed

  3. Run tests

    make test

  4. Format code

    make fmt

  5. Commit your changes

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

  6. Push to your fork

    git push origin feature/your-feature-name

  7. Open a Pull Request

    • Describe your changes clearly
    • Reference related issues
    • Ensure all CI checks pass

Commit Message Convention

We follow Conventional Commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Build/tooling changes
  • opt: - Performance optimization
  • security: - Security fixes

Examples:

feat: add support for custom IMAP ports
fix: handle connection timeout gracefully
docs: update installation instructions
test: add tests for IMAP connection pooling

Code Style Guidelines

Go Conventions

  • Follow Effective Go guidelines
  • Use gofmt for formatting (enforced by pre-commit hook)
  • Write meaningful variable and function names
  • Keep functions small and focused

Testing

  • Write tests for all new features
  • Maintain test coverage above 50%
  • Use table-driven tests for multiple scenarios
  • Mock external dependencies (IMAP servers)

Example test:

func TestSearchCriteria(t *testing.T) {
    tests := []struct {
        name     string
        criteria *SearchCriteria
        want     int
    }{
        {
            name: "search unread emails",
            criteria: &SearchCriteria{
                UnreadOnly: true,
            },
            want: 5,
        },
        // ... more test cases
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
        })
    }
}

Documentation

  • Add godoc comments for exported functions
  • Update README.md for user-facing changes
  • Update README.zh-CN.md for Chinese documentation
  • Include examples in documentation

Types of Contributions

Bug Fixes

  1. Check existing issues for bug reports
  2. Create a new issue if none exists
  3. Include steps to reproduce
  4. Add tests that fail without the fix
  5. Submit the fix with tests

New Features

  1. Open an issue to discuss the feature first
  2. Get feedback from maintainers
  3. Implement the feature with tests
  4. Update documentation
  5. Submit a pull request

Documentation

  • Fix typos and grammar
  • Improve clarity of explanations
  • Add more examples
  • Translate documentation to other languages

Performance Improvements

  • Profile the code to identify bottlenecks
  • Propose changes with benchmarks
  • Show before/after performance metrics

Pull Request Guidelines

Title

Use conventional commit format:

feat: add TEXT search support
fix: handle IMAP connection timeout
docs: update README with new features

Description

Include:

  • What changes were made
  • Why the changes are needed
  • How the changes work
  • Testing done
  • Screenshots (if applicable)

Review Process

  1. Automated checks (CI) must pass
  2. Code review by maintainers
  3. Address review feedback
  4. Squash commits if needed
  5. Merge into main branch

Reporting Issues

Bug Reports

Include:

  • mailcli version (mailcli version)
  • OS and architecture
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Error messages or logs

Feature Requests

Include:

  • Clear description of the feature
  • Use case or problem it solves
  • Proposed solution (if any)
  • Alternative approaches considered

Community Guidelines

  • Be respectful and constructive
  • Welcome newcomers and help them learn
  • Focus on what is best for the community
  • Show empathy towards other community members

Getting Help

  • Check existing documentation
  • Search existing issues
  • Ask questions in issues or discussions
  • Join community discussions

Recognition

Contributors will be:

  • Listed in the contributors section
  • Acknowledged in release notes
  • Credited in significant contributions

Thank you for contributing to mailcli! 🎉