Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
193 lines (149 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

193 lines (149 loc) · 4.64 KB

Contributing to Telegram Keyword Search Bot

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on the code, not the person
  • Help others learn and grow

How to Contribute

Reporting Bugs

  1. Check existing issues - Make sure the bug hasn't been reported
  2. Provide details - Include:
    • Python version
    • Telethon version
    • Bot version
    • Steps to reproduce
    • Expected vs actual behavior
    • Error messages/logs
  3. Use the bug template - Click "New Issue" and select the bug template

Suggesting Features

  1. Check existing issues - Avoid duplicates
  2. Describe the feature - Explain:
    • What problem it solves
    • How it should work
    • Example use cases
  3. Discuss alternatives - Show you've thought about the design

Submitting Code

  1. Fork the repository

    git clone https://github.com/yourusername/telegram-keyword-search-bot.git
cd telegram-keyword-search-bot

  2. Create a feature branch

    git checkout -b feature/your-feature-name

  3. Make your changes

    • Follow PEP 8 style guide
    • Add docstrings to functions
    • Add type hints where possible
    • Test your changes thoroughly
    • Update relevant documentation

  4. Commit with clear messages

    git commit -m "feat: add feature description"
git commit -m "fix: resolve issue #123"
git commit -m "docs: update README"

  5. Push and create a Pull Request

    git push origin feature/your-feature-name

Code Style

  • Python: Follow PEP 8
  • Formatting: Use consistent indentation (4 spaces)
  • Naming: Use descriptive names for variables, functions, classes
  • Comments: Explain the "why", not the "what"
  • Type Hints: Add type hints for better code clarity
  • Docstrings: Use Google-style docstrings for all functions

Example Function

async def search_messages(
    client: TelegramClient,
    keywords: List[str],
    start_date: datetime,
    end_date: datetime,
) -> List[Tuple[Any, Any]]:
    """
    Search for keywords in user's chats.
    
    Args:
        client: Telegram client instance
        keywords: List of keywords to search for
        start_date: Search start date (UTC)
        end_date: Search end date (UTC)
        
    Returns:
        List of (dialog, message) tuples matching the search
        
    Raises:
        ValueError: If date range is invalid
    """
    # Implementation

Testing

  • Test your changes locally before submitting
  • Include test cases for new features
  • Verify existing functionality still works
  • Test with multiple scenarios if possible

Pull Request Process

  1. Title: Use clear, descriptive titles

    • fix: handle null messages in search
    • feat: add export to file functionality
    • docs: improve setup instructions

  2. Description: Include:

    • What changed and why
    • Related issue numbers (e.g., Closes #123)
    • Testing steps
    • Any breaking changes

  3. Checklist:

    - [ ] Code follows style guidelines
- [ ] Docstrings added/updated
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No new warnings generated

Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Install development tools (optional)
pip install pytest black flake8

# Run the bot
python main.py

Project Structure

├── main.py              # Bot logic and command handlers
├── session_manager.py   # User session management
├── searcher.py          # Search functionality
├── requirements.txt     # Python dependencies
├── README.md            # User documentation
├── CONTRIBUTING.md      # This file
├── CHANGELOG.md         # Version history
└── bot.log             # Generated by the bot

Areas for Contribution

High Priority

  • Bug fixes
  • Documentation improvements
  • Error handling enhancements
  • Performance optimizations
  • Security improvements

Nice to Have

  • Advanced search filters
  • Search history database
  • Export results functionality
  • Bulk operations
  • Web dashboard

Questions?

  • Check existing issues and discussions
  • Read the documentation in README.md
  • Create a new discussion for questions

Recognition

Contributors will be:

  • Listed in the README.md
  • Acknowledged in CHANGELOG.md
  • Credited in GitHub commits

Thank you for contributing! 🎉