Workflow

Workflow

Keep development changes small, validation explicit, and impact understandable. The repository uses Taskfile.yml as the main automation entrypoint: Python/code work runs through uv, docs/frontend work runs through pnpm, and cross-workspace tasks are orchestrated by Turbo.

Development environment setup

This section guides external developers from zero to a working development environment.

Prerequisites

• Python 3.13 (requires-python = ">=3.13, <3.14")
• uv — Python package and project manager
• Node.js 22+ and pnpm — for docs site and frontend workspace
• git

Install

1. Clone the repository:

   git clone https://github.com/xinvxueyuan/lingchu-bot.git
   cd lingchu-bot

2. Install all dependencies (Python + Node.js):

   task install

   This runs uv sync and pnpm install. To install separately:

   uv sync --frozen       # Python dependencies
   pnpm install --frozen-lockfile  # Node.js dependencies

3. Copy the environment template:

   cp .env.example .env

   Edit .env to set LINGCHU_SUPERUSERS, SUPERUSERS, and adapter connection details for your environment.

4. Verify the setup:

   task check    # Static checks, format, Markdown lint, type check
   task test     # Python tests + docs tests

   If both pass, the environment is ready for development.

Development workflow

The typical development cycle:

1. Create a branch: git checkout -b feature/your-feature

2. Make changes following existing patterns and style.

3. Run focused checks on changed files:

   uv run -m ruff check path/to/file.py
   uv run -m ruff format path/to/file.py

4. Run the full check suite before committing:

   task check
   task test

5. Commit with gitmoji + Conventional Commits format (enforced by .husky/commit-msg).

6. Push and open a PR following the PR description guidelines.

Testing

Building

task build      # Build all workspaces (Python + docs)
pnpm turbo run build --filter=docs  # Build docs site only
uv build --clear  # Build Python package only

i18n workflow

When changing translatable strings:

task i18n   # Extract, update, and compile gettext catalogs

This runs pybabel extract, pybabel update, and pybabel compile. See Internationalization for details.

Recommended steps

Automation entrypoints

Prefer these Taskfile tasks:

task install
task check
task test
task build
task ci
task i18n

For Python-only changes, use focused uv run ... checks when appropriate. For docs or frontend-package changes, use focused pnpm --filter docs ... or pnpm turbo run ... checks.

Tooling map

Protecting the workspace

Do not revert, format, or rewrite files unrelated to the current task. When existing changes are present, assume by default that they came from another contributor or an earlier work session.

Branches and commits

Common branch prefixes:

GitHub Actions also match branches such as feature/**, fix/**, hotfix/*, releases/**, main, and dev. The actual target branch should follow maintainer or PR-page guidance.

Commit messages must follow gitmoji + Conventional Commits. See Commit Style.

🐛 fix: 修复成员禁言成功反馈
📝 docs: 重写文档站
✅ test: 增加群管理异常覆盖

PR description

A PR should explain:

• Purpose of the change.
• Key implementation details.
• GitNexus impact analysis results.
• Checks that were run.
• Open items or known risks.

If the PR touches the documentation site or internationalization, note whether Markdown lint, docs lint/test/build, and task i18n were run.