# How to Contribute to the ZhuLinsen Daily Stock Analysis Project: Complete Guide

> Learn how to contribute to the ZhuLinsen daily stock analysis project. Follow our guide for forking, setting up, and submitting pull requests easily.

- Repository: [mumu/daily_stock_analysis](https://github.com/ZhuLinsen/daily_stock_analysis)
- Tags: how-to-guide
- Published: 2026-04-30

---

**Yes, you can contribute to the ZhuLinsen/daily_stock_analysis project by following the structured workflow defined in [`docs/CONTRIBUTING.md`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/docs/CONTRIBUTING.md), which includes forking the repository, setting up a local development environment with Python virtual environments, running the CI gate script, and submitting pull requests using Conventional Commits.**

The ZhuLinsen/daily_stock_analysis repository is an open-source, AI-driven stock analysis platform that welcomes contributions from Python developers, data scientists, and AI researchers. Whether you want to fix bugs, add new notification channels, extend the AI agent capabilities under `src/agent/`, or improve the FastAPI backend, the project provides comprehensive contribution guidelines and a well-organized modular architecture to help you get started immediately.

## Repository Structure and Prerequisites

The project follows a full-stack architecture with clear separation of concerns. Before contributing, familiarize yourself with the directory layout:

- **`src/`** – Core backend logic including the analysis pipeline, services, and AI agents
- **`api/`** – FastAPI application definition ([`api/app.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/api/app.py))
- **`apps/dsa-web/`** – Optional React-based web UI frontend
- **`tests/`** – Unit and integration tests mirroring the source structure
- **`docs/`** – Project documentation including [`CONTRIBUTING.md`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/CONTRIBUTING.md) and changelogs

You will need Python 3.x installed, along with `git` for version control. The project uses standard Python tooling including `flake8` for linting and `pytest` for testing.

## Setting Up Your Development Environment

### Fork and Clone the Repository

Start by creating your own fork of the repository on GitHub, then clone it locally:

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

```

### Install Dependencies and Configure Environment

Create an isolated Python environment and install the required dependencies:

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

pip install -r requirements.txt

```

Copy the environment template to create your local configuration:

```bash
cp .env.example .env

```

Edit `.env` to add your API keys and configure stock lists for local testing.

## Contribution Workflow

### Run the Local CI Gate

Before making any changes, verify your environment works by running the CI gate script:

```bash
./scripts/ci_gate.sh

```

This script enforces code quality by running `py_compile` syntax checks, `flake8` linting, and offline `pytest` tests. Running this locally prevents CI failures after you push your changes.

### Create a Feature Branch

Always work on a dedicated branch rather than `main`:

```bash
git checkout -b feature/your-feature-name

```

### Implement Your Changes Following Code Standards

When modifying code, adhere to **PEP 8** style guidelines and include comprehensive docstrings. Keep changes within their architectural boundaries:

- Backend logic belongs in `src/`
- FastAPI endpoints belong in `api/`
- Web UI modifications belong in `apps/dsa-web/`
- AI agent strategies belong in `src/agent/agents/`

The entry point [`main.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/main.py) parses CLI options and coordinates the pipeline, while [`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py) orchestrates data fetching, AI analysis, and notification steps.

### Add or Update Tests

Place new test files in the `tests/` directory, following the existing naming conventions like [`test_stock_analyzer_bias.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/test_stock_analyzer_bias.py) or [`test_market_review.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/test_market_review.py). Ensure your tests cover both unit functionality and integration scenarios.

### Commit Using Conventional Commits

Write clear commit messages following the Conventional Commits specification:

```bash
git commit -m "feat: add custom webhook notification channel"
git commit -m "fix: resolve bias calculation in technical agent"
git commit -m "docs: update API endpoint documentation"

```

### Submit Your Pull Request

Push your branch to your fork and open a Pull Request on GitHub:

```bash
git push origin feature/your-feature-name

```

The CI pipeline automatically runs checks including **backend-gate**, **docker-build**, **web-gate**, and **network-smoke** tests defined in [`.github/workflows/ci.yml`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/.github/workflows/ci.yml).

## Key Architectural Components for Contributors

Understanding these core files helps you make effective contributions to the ZhuLinsen/daily_stock_analysis project:

### Entry Points and Pipeline Orchestration

**[`main.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/main.py)** serves as the CLI entry point that bootstraps the environment and coordinates the full analysis pipeline. **[`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py)** contains the central orchestration logic that sequences data fetching, AI processing, notification sending, and optional market review steps.

### Configuration and Services

**[`src/config.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/config.py)** loads environment variables via `dotenv`, validates them, and provides a singleton `Config` object used throughout the codebase. Individual responsibilities are split into modular services:

- **[`src/services/stock_service.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/services/stock_service.py)** – Handles stock data fetching and normalization
- **[`src/services/report_renderer.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/services/report_renderer.py)** – Generates Markdown and HTML reports
- **`src/services/notification_sender/`** – Contains notification channel implementations

### AI Agent Layer

The AI "agent" stack lives under **`src/agent/`**, providing modular strategies for chat-based stock queries. For example, **[`src/agent/agents/technical_agent.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/agent/agents/technical_agent.py)** implements technical analysis capabilities that contributors can extend or replicate for new analysis types.

### Web Interface Components

**[`api/app.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/api/app.py)** defines the FastAPI application, while **[`src/webui_frontend.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/webui_frontend.py)** prepares and compiles static assets for the React-based UI. When running locally with `python main.py --webui`, the system serves the frontend on `0.0.0.0:8000` alongside the API.

## Practical Contribution Examples

### Adding a New Notification Channel

To add a custom webhook sender, create a new file in the notification services:

```python

# src/services/notification_sender/custom_webhook_sender.py

import requests
from .notification_sender import NotificationSender

class CustomWebhookSender(NotificationSender):
    def __init__(self, webhook_url: str):
        self.webhook_url = webhook_url
    
    def send(self, content: str, **kwargs) -> bool:
        response = requests.post(
            self.webhook_url, 
            json={"text": content}
        )
        return response.ok

```

Register the new sender in [`src/config.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/config.py) or via environment variables so the pipeline in [`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py) automatically picks it up during execution.

### Running Single-Stock Analysis for Testing

Test your changes locally without triggering the full daily scan:

```bash
python main.py --debug --stocks 600519,000001

```

The `--debug` flag enables verbose logging, while `--stocks` overrides the `STOCK_LIST` configured in `.env` to analyze only specific securities.

### Testing the Web UI Locally

Verify frontend integration by starting the complete stack:

```bash
python main.py --webui

```

This launches the FastAPI backend and serves the React-based UI at `http://0.0.0.0:8000`, allowing you to test API endpoints and frontend components simultaneously.

## Summary

- **Fork and clone** the ZhuLinsen/daily_stock_analysis repository, then install dependencies via [`requirements.txt`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/requirements.txt) and copy `.env.example` to `.env`
- **Run [`./scripts/ci_gate.sh`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/./scripts/ci_gate.sh)** locally before committing to ensure your code passes linting, compilation, and unit tests
- **Follow architectural boundaries** when contributing: backend logic goes in `src/`, FastAPI routes in `api/`, web UI in `apps/dsa-web/`, and AI agents in `src/agent/`
- **Use Conventional Commits** (e.g., `feat:`, `fix:`, `docs:`) to maintain clean history and enable automated changelog generation
- **Add corresponding tests** in the `tests/` directory for any new functionality or bug fixes
- **Update documentation** in [`docs/CHANGELOG.md`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/docs/CHANGELOG.md) or [`README.md`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/README.md) when adding user-visible features

## Frequently Asked Questions

### Do I need financial expertise to contribute to the ZhuLinsen daily stock analysis project?

No, financial expertise is not required. While domain knowledge helps when modifying AI agents in `src/agent/`, many contributions focus on infrastructure, testing, documentation, notification channels, or the FastAPI backend. The modular architecture allows developers to improve code quality, add features like new notification senders, or enhance the React UI without deep stock market knowledge.

### What Python version is required for contributing?

The project requires Python 3.x, though you should check the specific version constraints in [`requirements.txt`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/requirements.txt) and the CI configuration in [`.github/workflows/ci.yml`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/.github/workflows/ci.yml). The `py_compile` check in [`./scripts/ci_gate.sh`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/./scripts/ci_gate.sh) validates syntax compatibility across supported Python versions.

### How do I report a bug if I cannot fix it myself?

You can open an issue on the GitHub repository describing the bug with reproduction steps, expected behavior, and actual behavior. Include relevant log outputs from running with `--debug` mode and specify which component is affected (e.g., [`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py), [`src/services/stock_service.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/services/stock_service.py), or the notification system). Clear bug reports help maintainers identify whether the issue lies in data fetching, AI analysis, or report generation.

### Can I contribute documentation improvements only?

Yes, documentation contributions are welcome and follow the same workflow as code changes. Update relevant sections in [`README.md`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/README.md), [`docs/CONTRIBUTING.md`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/docs/CONTRIBUTING.md), or add inline docstrings to functions in [`src/config.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/config.py) or [`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py). Use the `docs:` prefix in your Conventional Commit messages when submitting documentation-only pull requests.