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

Yes, you can contribute to the ZhuLinsen/daily_stock_analysis project by following the structured workflow defined in 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)
• apps/dsa-web/ – Optional React-based web UI frontend
• tests/ – Unit and integration tests mirroring the source structure
• docs/ – Project documentation including 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:

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:

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:

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:

./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:

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 parses CLI options and coordinates the pipeline, while 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 or 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:

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:

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.

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 serves as the CLI entry point that bootstraps the environment and coordinates the full analysis pipeline. 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 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 – Handles stock data fetching and normalization
• 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 implements technical analysis capabilities that contributors can extend or replicate for new analysis types.

Web Interface Components

api/app.py defines the FastAPI application, while 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:

# 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 or via environment variables so the pipeline in 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:

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:

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 and copy .env.example to .env
• Run ./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 or 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 and the CI configuration in .github/workflows/ci.yml. The py_compile check in ./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, 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, docs/CONTRIBUTING.md, or add inline docstrings to functions in src/config.py or src/core/pipeline.py. Use the docs: prefix in your Conventional Commit messages when submitting documentation-only pull requests.

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