🤝 Contributing - How to Contribute to PyDoll MCP Server Project

Thank you for your interest in the PyDoll MCP Server project! This guide will help you understand how to contribute to the project.

🌟 Contribution Overview

Types of Contributions

We welcome various forms of contributions:

• 🐛 Bug Reports: Finding and reporting issues
• ✨ Feature Suggestions: Proposing new feature ideas
• 💻 Code Contributions: Implementing features or fixing bugs
• 📚 Documentation Improvements: Enhancing guides, examples, and API documentation
• 🧪 Testing Additions: Writing test code and improving coverage
• 🎨 UI/UX Improvements: Enhancing user experience
• 🌍 Translation: Supporting project internationalization

Getting Started

1. Fork the Repository

   git clone https://github.com/JinsongRoh/pydoll-mcp.git
   cd pydoll-mcp
   

2. Set Up Development Environment

   # Create virtual environment
   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\\Scripts\\activate   # Windows
   
   # Install dependencies
   pip install -r requirements.txt
   pip install -e ".[dev]"
   

3. Install Pre-commit Hooks

   pre-commit install
   pre-commit install --hook-type commit-msg
   

4. Run Tests

   pytest tests/ -v
   

🐛 Bug Reports

Before Submitting a Bug Report

1. Check Existing Issues - Prevent duplicate reports
2. Update to Latest Version - Verify the issue still exists
3. Test with Minimal Configuration - Isolate the problem

Bug Report Template

**Environment Information:**
- PyDoll MCP Server: v1.1.3
- Python: 3.11.0
- OS: Windows 11 / macOS 14 / Ubuntu 22.04
- Browser: Chrome 120.0.6099.109

**Bug Description:**
Clear description of the bug that occurred

**Steps to Reproduce:**
1. First step
2. Second step
3. Third step

**Expected Behavior:**
What you expected to happen

**Actual Behavior:**
What actually happened

**Error Logs:**

Paste error logs here

**Additional Information:**
Any other relevant information

✨ Feature Suggestions

Feature Suggestion Template

**Feature Summary:**
Brief description of the proposed feature

**Problem Definition:**
What problem does this feature aim to solve?

**Proposed Solution:**
How would you like this feature to work?

**Alternative Solutions:**
Other approaches you've considered

**Use Cases:**
- Use case 1: ...
- Use case 2: ...

**Implementation Ideas:**
Technical suggestions (optional)

**Priority:**
Low / Medium / High

💻 Code Contributions

Development Workflow

1. Create Feature Branch

   git checkout -b feature/your-feature-name
   git checkout -b bugfix/issue-number
   

2. Make Changes

   • Follow coding standards
   • Add tests for new features
   • Update documentation
   • Ensure all tests pass

3. Write Commits

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

4. Push and Create Pull Request

   git push origin feature/your-feature-name
   

Coding Standards

Python Code Style

We use the following tools for code quality:

• Black: Code formatting
• Ruff: Linting and code analysis
• MyPy: Type checking
• isort: Import sorting

# Code formatting
black .

# Linting check
ruff check .

# Type checking
mypy pydoll_mcp/

# Import sorting
isort .

Documentation Style

Use Google-style docstrings:

def function_example(param1: str, param2: int = 0) -> bool:
    """One-line summary description.
    
    Longer description if needed. Can span multiple lines and
    should provide additional information about the function.
    
    Args:
        param1: Description of the first parameter.
        param2: Description of the second parameter. Defaults to 0.
        
    Returns:
        Description of the return value.
        
    Raises:
        ValueError: Condition when this exception is raised.
        RuntimeError: Condition when this exception is raised.
        
    Example:
        Basic usage example:
        
        ```python
        result = function_example("test", 5)
        print(result)  # True
        ```
    """
    if not param1:
        raise ValueError("param1 cannot be empty")
    
    return len(param1) > param2

Testing Guidelines

Running Tests

# Run all tests
pytest

# Run specific test categories
pytest -m unit
pytest -m integration
pytest -m browser

# Run with coverage
pytest --cov=pydoll_mcp --cov-report=html

# Run performance tests
pytest -m performance --benchmark-only

Pull Request Guidelines

Pre-submission Checklist

• All tests pass
• Code is properly formatted
• Documentation is updated
• Changelog updated (if applicable)
• No merge conflicts

Pull Request Template

## Description

Brief description of the changes.

## Type of Change

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

## Related Issues

Fixes #123
Closes #456

## Changes Made

- Added feature X
- Fixed bug Y
- Updated documentation Z

## Testing

- [ ] Added unit tests
- [ ] Added integration tests
- [ ] Performed manual testing
- [ ] All existing tests pass

## Checklist

- [ ] Followed the project's coding standards
- [ ] Performed self-review of code
- [ ] Commented code, particularly in hard-to-understand areas
- [ ] Made corresponding changes to documentation
- [ ] Generated no new warnings
- [ ] Added tests that prove the fix or feature works
- [ ] New and existing unit tests pass locally with changes

📚 Documentation Contributions

Documentation Types

• API Documentation: Function/class docstrings
• User Guide: Installation, configuration, usage
• Examples: Code examples and tutorials
• Developer Documentation: Architecture, contribution guidelines

Documentation Standards

• Use clear and concise language
• Provide practical examples
• Include error handling
• Keep documentation synchronized with code changes

Building Documentation

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation locally
mkdocs serve

# View at http://localhost:8000

🧪 Testing Contributions

Adding Tests

1. Identify Untested Code:

   pytest --cov=pydoll_mcp --cov-report=html
   open htmlcov/index.html
   

2. Write Comprehensive Tests:

   • Happy path tests
   • Error condition tests
   • Edge case tests

3. Add Performance Tests for Critical Paths

Test Environment

# Set up test environment
export PYDOLL_TEST_MODE=true
export PYDOLL_HEADLESS=true

# Run specific test types
pytest tests/unit/
pytest tests/integration/
pytest tests/browser/

🚀 Release Process

Version Management

We follow [Semantic Versioning](https://semver.org/):

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Release Checklist

• Update version in pyproject.toml
• Update version in pydoll_mcp/__init__.py
• Update CHANGELOG.md
• Write release notes
• Create release tag: git tag v1.0.0
• Push tags: git push --tags

🤝 Community Guidelines

Code of Conduct

To provide an inclusive and welcoming environment, please:

• Respect different perspectives and experiences
• Be collaborative and help others learn
• Be patient with beginners
• Provide constructive feedback and criticism

Communication Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions and community chat
• Pull Requests: Code reviews and technical discussions

Recognition

Contributors are recognized through:

• Listed in project README
• Mentioned in release notes
• Invited to contributor team for significant contributions

🛠️ Development Tools

Recommended Tools

• IDE: VS Code, PyCharm, or similar
• Git GUI: GitKraken, SourceTree, or command line
• Terminal: Windows Terminal, iTerm2, or similar
• Browser: Chrome DevTools for debugging

VS Code Setup

Recommended extensions:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.black-formatter",
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker",
    "ms-python.pylint",
    "ms-toolsai.jupyter"
  ]
}

Environment Variables

# Development environment
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG
export PYDOLL_BROWSER_TYPE=chrome
export PYDOLL_HEADLESS=false

📋 Troubleshooting

Common Development Issues

Import Errors

# Solution: Install in editable mode
pip install -e .

Test Failures

# Solution: Check environment
pytest tests/test_specific.py -v -s

Browser Issues

# Solution: Verify browser installation
python -c "from pydoll.browser import Chrome; print('OK')"

Getting Help

1. Check existing documentation
2. Search GitHub issues
3. Ask in GitHub Discussions
4. Create detailed issue

🎉 Thank You!

Thank you for contributing to PyDoll MCP Server! Your contributions make browser automation more accessible and powerful for everyone.

License

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

---

Happy Contributing! 🚀

For more information, visit the [GitHub repository](https://github.com/JinsongRoh/pydoll-mcp).