Development workflow

Keep development changes small, validation explicit, and impact understandable. The repository uses Turborepo as the unified task orchestrator: root tasks (//#py:*, //#md:*, //#js:* — scripts in root package.json) cover the Python toolchain, while workspace packages (apps/docs, apps/lingc-cli) own their lint / type / test / build tasks. Taskfile.yml is a thin delegation shell — task check / task test / task build / task format / task fix / task ci:* are single-line pnpm turbo run ... calls — and keeps release / version / db / hooks / smoke tasks that need secrets or CLI arg passthrough.

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 and adapter connection details for your environment.

4. Verify the setup:

   task check    # Static checks, format, Markdown lint, type check
   task test     # Root pytest + lingc-cli 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

Test type	Command	Scope
Python unit tests	uv run -m pytest	All Python tests
Python focused tests	uv run -m pytest tests/handle/commands/test_mute.py	Single test file
Docs tests	pnpm --filter docs test	Vitest component/unit tests
Docs build	pnpm turbo run build --filter=docs	Static docs output and Starlight/Pagefind generation
E2E tests	pnpm --filter docs exec playwright test	Playwright browser tests
Full CI sequence	task ci	check + test + build

Building

task build      # Build all workspaces (root wheel + lingc-cli + 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

1. Clarify the goal

   Clarify the goal, success criteria, and out-of-scope items before writing any code.

2. Check existing changes

   Run git status --short and confirm existing changes. Assume by default that existing changes came from another contributor or an earlier work session.

3. Read related code

   Read related code and tests, preferring existing structure. Use GitNexus or codegraph to understand code structure and relationships.

4. Analyze impact

   Run GitNexus or codegraph impact analysis before changing functions, classes, or methods.

5. Implement and test

   Implement the smallest useful change and add tests.

6. Run checks

   Run the relevant checks through task check, task test, or focused uv / pnpm commands.

7. Verify change scope

   Run GitNexus detect changes before committing.

Translatable strings

When changing translatable strings, synchronize the Babel catalogs as well. See Internationalization.

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

GitNexus / codegraph

Understand code structure, impact, and change scope

Context7

Query current documentation for libraries, frameworks, SDKs, CLI tools, or cloud services

Husky / prek

Local Git hooks and pre-commit checks

Turbo

Cross-workspace lint, type check, and build orchestration for docs and packages

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:

Prefix	Purpose
feature/	New features
fix/	Bug fixes
hotfix/	Urgent production fixes
docs/	Documentation changes
refactor/	Code refactoring

GitHub Actions also match branches such as feature/**, fix/**, hotfix/*, main, and dev. Formal releases are manual-trigger only — see Cut a release — so no releases/** branches are pushed. 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.