How to Contribute to TrendRadar: A Complete Guide for New Contributors

Fork the repository, set up a Python 3.10+ environment, and submit a PR with clear documentation and tests.

TrendRadar is a lightweight, highly-configurable hot-news aggregator that pulls data from Chinese and global platforms, supports RSS feeds, and offers AI-driven analysis. This guide walks you through how to contribute to TrendRadar effectively, whether you're fixing bugs, adding new platforms, or improving AI analysis features.

---

Understand the Architecture Before Contributing

TrendRadar's modular design makes it straightforward to locate where your contribution fits. Understanding these components helps you contribute to the right area:

Component	Purpose	Key Files
Configuration loader	Reads config/config.yaml, frequency_words.txt, and AI files	trendradar/core/loader.py
Scheduler	Interprets timeline.yaml to trigger crawls and pushes	trendradar/core/scheduler.py
Crawler	Fetches hot-list data from configured platforms	trendradar/crawler/
Storage	Persists daily snapshots in SQLite or S3	trendradar/storage/local.py
Report generator	Builds HTML/email output	trendradar/report/generator.py
Notification layer	Dispatches to multiple channels with multi-account support	trendradar/notification/, trendradar/core/config.py
AI analysis	LLM-powered content analysis	trendradar/ai/client.py, trendradar/ai/analyzer.py

---

Ways to Contribute to TrendRadar

Core Code Improvements

Contribute bug fixes, performance optimizations, or refactor the scheduler and storage layers. Work in trendradar/core/* and trendradar/storage/*.

New Platform Support

Add a new hot-list source (e.g., a Chinese forum or international platform):

1. Edit config/config.yaml → platforms.sources
2. Implement a parser in trendradar/crawler/
3. Register the parser in trendradar/crawler/__init__.py

RSS Feed Enhancements

Add or adjust RSS sources, improve freshness filtering. Modify config/config.yaml → rss.feeds and trendradar/crawler/rss/fetcher.py.

Keyword and AI Filtering

Extend frequency_words.txt syntax or create AI interest files (ai_interests.txt). Update files under config/ and filter logic in trendradar/core/frequency.py & trendradar/ai/filter.py.

AI Analysis Improvements

Improve prompt templates, add new analysis modes, or support additional LLM providers. Work in config/ai_analysis_prompt.txt, trendradar/ai/client.py, and trendradar/ai/analyzer.py.

Documentation and Tests

Update README.md, README-EN.md, or add inline documentation. Add unit tests under tests/ and fix GitHub Actions workflows in .github/workflows/crawler.yml.

---

Getting Started: Environment Setup

Follow these steps to set up your development environment and contribute to TrendRadar:

1. Fork the repository on GitHub

2. Clone your fork

   git clone https://github.com/<your-username>/TrendRadar.git
   cd TrendRadar

3. Create a virtual environment (Python 3.10+ required)

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   
   pip install -r requirements.txt

4. Verify your setup

   python -m trendradar  # or python main.py depending on entrypoint
   

5. Make your changes, following existing code style (PEP 8, type hints)

6. Run linting before committing

   black .
   flake8

7. Commit and push with a clear message, then open a Pull Request

8. Fill the PR template describing motivation, files touched, and any migration steps

---

Example: Adding a New Platform to TrendRadar

Here's a complete walkthrough for adding Bilibili's "Game" hot list:

1. Add source entry in config/config.yaml:

   platforms:
     sources:
       - id: "bilibili-game"
         name: "Bilibili 游戏热搜"

2. Create the parser at trendradar/crawler/bilibili_game.py. Use the existing Bilibili hot-search module as a template.

3. Register the parser in trendradar/crawler/__init__.py so the core loader can discover it.

4. Test locally:

   python -m trendradar

   Verify data appears in output/news/*.db.

5. Update documentation – add the new platform to the "平台配置" table in README.md.

---

Example: Improving AI Prompt Templates

To refine the tone of AI-generated analysis:

1. Open config/ai_analysis_prompt.txt

2. Edit the system prompt or example outputs

3. Test with your API key:

   export AI_API_KEY="your-key"
   python -m trendradar --ai-analysis

4. Document changes in your PR description

The prompt loading logic is in trendradar/ai/prompt_loader.py.

---

Key Files You'll Frequently Touch

File	Role
README.md / README-EN.md	User guide and contribution notes
config/config.yaml	Central configuration (platforms, schedule, report)
trendradar/core/loader.py	Loads all config sections, merges env vars
trendradar/core/scheduler.py	Timeline scheduler, resolves when to crawl/push/AI
trendradar/crawler/	Platform fetchers
trendradar/storage/	SQLite/S3 storage layer, incremental detection
trendradar/report/generator.py	HTML/email report generation
trendradar/notification/	Message formatting and multi-account handling
trendradar/ai/	AI client, prompt loader, filter, analyzer
.github/workflows/crawler.yml	CI workflow running the crawler on schedule
docker/manage.py	Docker container helper

---

Important Tips for Contributing to TrendRadar

• Keep the schedule in sync – when adding a platform that should crawl only on weekdays, update config/timeline.yaml accordingly.

• Respect the max-account limit – the limit_accounts helper in trendradar/core/config.py caps webhook accounts per channel; adjust only if you understand the impact on GitHub Actions runtimes.

• Run linting and formatting – use black and flake8 before pushing.

• Add tests – new platform parsers should have unit tests feeding sample HTML and asserting non-empty results. Place tests under tests/ using pytest.

---

PR Checklist: Before You Submit

• Code follows existing style and includes type hints
• Updated README.md or README-EN.md for user-facing changes
• Added or updated config examples (e.g., new platform entry)
• Local run passes without errors and new feature appears in generated report
• All CI jobs (.github/workflows/crawler.yml) succeed after changes

---

Summary

• TrendRadar is a modular hot-news aggregator with clear separation between configuration, crawling, storage, AI analysis, and notification layers.

• To contribute to TrendRadar, fork the repo, set up Python 3.10+, make your changes in the appropriate module, run black and tests, and submit a detailed PR.

• Key contribution areas include new platform parsers, RSS improvements, AI prompt refinements, notification channels, and documentation updates.

• Always update config/config.yaml, relevant code modules, and README.md together when adding features.

---

Frequently Asked Questions

What programming language and version does TrendRadar require?

TrendRadar requires Python 3.10 or higher. The project uses modern Python features including type hints and dataclasses. Always verify your environment with python --version before installing dependencies.

How do I add a new platform source to TrendRadar?

Add an entry to config/config.yaml under platforms.sources with a unique id and name, then implement a parser in trendradar/crawler/ following existing examples. Register the parser in trendradar/crawler/__init__.py and test locally before submitting your PR.

Where should I put tests for my contribution?

Place unit tests under the tests/ directory using pytest. For new platform parsers, create a test that feeds sample HTML and asserts the parser returns non-empty, correctly structured data. Follow the existing test structure if present.

What code style should I follow when contributing to TrendRadar?

Follow PEP 8 with type hints on function signatures. Run black . for automatic formatting and flake8 for linting before committing. Keep functions focused and maintain the modular structure seen in existing code.

Does TrendRadar have a license requirement for reuse?

Yes. The README.md includes a "二次开发与引用" (secondary development and citation) note in lines 12-16 that requires proper attribution when reusing TrendRadar code. Include appropriate credit and link back to the original repository when incorporating code into other projects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}