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

> New to TrendRadar? Learn how to contribute to the sansan0/TrendRadar repository by forking the repo, setting up Python 3.10+, and submitting your first PR with clear documentation and tests.

- Repository: [sansan/TrendRadar](https://github.com/sansan0/TrendRadar)
- Tags: how-to-guide
- Published: 2026-04-22

---

**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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml), [`frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/frequency_words.txt), and AI files | [`trendradar/core/loader.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/core/loader.py) |
| **Scheduler** | Interprets [`timeline.yaml`](https://github.com/sansan0/TrendRadar/blob/main/timeline.yaml) to trigger crawls and pushes | [`trendradar/core/scheduler.py`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/storage/local.py) |
| **Report generator** | Builds HTML/email output | [`trendradar/report/generator.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/report/generator.py) |
| **Notification layer** | Dispatches to multiple channels with multi-account support | `trendradar/notification/`, [`trendradar/core/config.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/core/config.py) |
| **AI analysis** | LLM-powered content analysis | [`trendradar/ai/client.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/ai/client.py), [`trendradar/ai/analyzer.py`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) → `platforms.sources`
2. Implement a parser in `trendradar/crawler/`
3. Register the parser in [`trendradar/crawler/__init__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/crawler/__init__.py)

### RSS Feed Enhancements

Add or adjust RSS sources, improve freshness filtering. Modify [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) → `rss.feeds` and [`trendradar/crawler/rss/fetcher.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/crawler/rss/fetcher.py).

### Keyword and AI Filtering

Extend [`frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/frequency_words.txt) syntax or create AI interest files ([`ai_interests.txt`](https://github.com/sansan0/TrendRadar/blob/main/ai_interests.txt)). Update files under `config/` and filter logic in [`trendradar/core/frequency.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/core/frequency.py) & [`trendradar/ai/filter.py`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/config/ai_analysis_prompt.txt), [`trendradar/ai/client.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/ai/client.py), and [`trendradar/ai/analyzer.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/ai/analyzer.py).

### Documentation and Tests

Update [`README.md`](https://github.com/sansan0/TrendRadar/blob/main/README.md), [`README-EN.md`](https://github.com/sansan0/TrendRadar/blob/main/README-EN.md), or add inline documentation. Add unit tests under `tests/` and fix GitHub Actions workflows in [`.github/workflows/crawler.yml`](https://github.com/sansan0/TrendRadar/blob/main/.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**

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

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

   ```bash
   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate

   pip install -r requirements.txt
   ```

4. **Verify your setup**

   ```bash
   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

   ```bash
   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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml):

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

2. **Create the parser** at [`trendradar/crawler/bilibili_game.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/crawler/bilibili_game.py). Use the existing Bilibili hot-search module as a template.

3. **Register the parser** in [`trendradar/crawler/__init__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/crawler/__init__.py) so the core loader can discover it.

4. **Test locally**:

   ```bash
   python -m trendradar
   ```

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

5. **Update documentation** – add the new platform to the "平台配置" table in [`README.md`](https://github.com/sansan0/TrendRadar/blob/main/README.md).

---

## Example: Improving AI Prompt Templates

To refine the tone of AI-generated analysis:

1. **Open** [`config/ai_analysis_prompt.txt`](https://github.com/sansan0/TrendRadar/blob/main/config/ai_analysis_prompt.txt)

2. **Edit** the system prompt or example outputs

3. **Test with your API key**:

   ```bash
   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`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/ai/prompt_loader.py).

---

## Key Files You'll Frequently Touch

| File | Role |
|------|------|
| [`README.md`](https://github.com/sansan0/TrendRadar/blob/main/README.md) / [`README-EN.md`](https://github.com/sansan0/TrendRadar/blob/main/README-EN.md) | User guide and contribution notes |
| [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) | Central configuration (platforms, schedule, report) |
| [`trendradar/core/loader.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/core/loader.py) | Loads all config sections, merges env vars |
| [`trendradar/core/scheduler.py`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/.github/workflows/crawler.yml) | CI workflow running the crawler on schedule |
| [`docker/manage.py`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/config/timeline.yaml) accordingly.

- **Respect the max-account limit** – the `limit_accounts` helper in [`trendradar/core/config.py`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/README.md) or [`README-EN.md`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/.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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml), relevant code modules, and [`README.md`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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.