Canonical source: CONTRIBUTING.md at the repository root — this page mirrors it on the docs site.

Contributing to trendspyg¶

Thank you for your interest in contributing to trendspyg! This document provides guidelines and instructions for contributing.

Code of Conduct¶

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

How to Contribute¶

Reporting Bugs¶

If you find a bug, please open an issue with: - A clear, descriptive title - Steps to reproduce the issue - Expected vs actual behavior - Your environment (Python version, OS) - Code samples if applicable

Suggesting Enhancements¶

Feature requests are welcome! Please open an issue describing: - The problem you're trying to solve - Your proposed solution - Why this would be useful to other users

Pull Requests¶

Fork the repository and create a new branch:

git checkout -b feature/your-feature-name

Make your changes:
Write clear, commented code
Follow existing code style (PEP 8)
Add type hints to all functions
Update documentation if needed
Add tests:
All new features must include tests
Ensure existing tests still pass
Aim for >90% code coverage on new code
Every module must stay at or above 80% coverage on its own — CI enforces this (python scripts/check_coverage_floor.py after a coverage run with --cov-report=json)
```
pytest tests/ -v --cov=trendspyg
```
Update documentation:
Update README.md if adding features
Add docstrings to new functions
Update CHANGELOG.md
Commit your changes:
Use clear, descriptive commit messages
Follow conventional commit format:
- feat: for new features
- fix: for bug fixes
- docs: for documentation
- test: for tests
- refactor: for code refactoring

Push and create a Pull Request:

git push origin feature/your-feature-name

Provide a clear PR description
Link any related issues
Wait for review and feedback

Development Setup¶

Clone the repository:

git clone https://github.com/flack0x/trendspyg.git
cd trendspyg

Install development dependencies:
```
pip install -e .[dev,analysis]
```
Run tests:
```
pytest tests/ -v
```
Run linting:
```
flake8 trendspyg/
mypy trendspyg/
```

API Stability (semver)¶

Since v1.0.0 the public API is under a written stability contract — STABILITY.md. For contributors this means:

Don't remove, rename, or change the behavior of anything covered (exported names, exception types, CLI commands/flags, MCP tools, schema fields) — that's a major-release decision, not a PR.
Additions are fine (new parameters must have defaults that preserve existing behavior) and land in a minor release.
tests/test_public_api.py pins trendspyg.__all__ exactly. If your PR changes the public surface, update that test and STABILITY.md in the same PR, deliberately.

Code Style¶

Follow PEP 8 guidelines
Use type hints for all function parameters and returns
Maximum line length: 100 characters
Use descriptive variable names
Add docstrings to all public functions

Example:

def download_google_trends_rss(
    geo: str = 'US',
    output_format: OutputFormat = 'dict'
) -> Union[List[Dict], str, 'pd.DataFrame']:
    """
    Download Google Trends RSS feed data.

    Args:
        geo: Country/region code (e.g., 'US', 'GB')
        output_format: Output format ('dict', 'json', 'csv', 'dataframe')

    Returns:
        Trend data in requested format

    Raises:
        InvalidParameterError: If parameters are invalid
    """

Testing Guidelines¶

Write tests for all new functionality
Use pytest for testing
Organize tests by module (test_rss_downloader.py, test_csv_downloader.py)
Include both positive and negative test cases
Test edge cases and error handling

Test structure:

class TestFeature:
    """Test feature functionality"""

    def test_basic_functionality(self):
        """Test basic feature usage"""
        result = my_function()
        assert result is not None

    def test_error_handling(self):
        """Test error conditions"""
        with pytest.raises(InvalidParameterError):
            my_function(invalid_param)

Documentation¶

Keep README.md up to date
Add docstrings to all public functions
Include examples for new features
Update CHANGELOG.md for all changes

Questions?¶

If you have questions about contributing, feel free to: - Open an issue with the question label - Reach out via GitHub discussions

Thank you for contributing to trendspyg! 🚀