3.4 KiB
Repository Guidelines
Project Structure & Module Organization
GYXX Flow is a Python 3.12 src-layout package. Framework code lives in src/gyxx_flow/; business implementations belong directly in src/gyxx_flow/modules/<module>/. The former runtime/ directories are compatibility namespaces only and must not receive new production code.
All project and module tests live in tests/. Configuration lives in config/, runbooks in docs/, and service scripts in deploy/. Treat var/ as generated state, not source; production deployments must set an external GYXX_DATA_ROOT.
Build, Test, and Development Commands
Use uv from the repository root:
uv sync --python 3.12 --group dev # create/update the development environment
uv run pytest # run the project test suite
uv run pytest tests/test_cli.py # run a focused test file
uv run ruff check src tests # lint imports and Python errors
uv build # create distribution artifacts
uv run gyxx doctor --json # validate local configuration
uv run gyxx list # inspect registered workflows
Workflow and command execution defaults to dry-run behavior. Add --execute only when real external effects are intended. Public manual commands must be declared in config/commands.json; never reintroduce recursive executable-script discovery.
Production schedules run only through the Python scheduler service; do not add Windows Task Scheduler registration. Manual commands remain dry-run by default, while gyxx schedule run executes enabled jobs unless --dry-run is supplied. PostgreSQL uses the cloud service selected through runtime-only credentials, both Hermes roles remain loopback-only, Feishu keeps the existing integration behavior, credentials must not have non-empty source defaults, and every browser entry must retain its unique CDP/Profile/Cookie/storage-state binding.
Each executable workflow_id compiles to a LangGraph StateGraph. Preserve the public workflow model, journal, lock, shadow, and effect-ledger contracts when changing graph execution. Check upstream drift with uv run gyxx sources status; automated source application is limited to untransformed, conflict-free entries and still requires --execute.
Coding Style & Naming Conventions
Follow existing Python conventions: four-space indentation, type annotations, concise docstrings, and imports ordered as standard library, third party, then local modules. Ruff enforces E4, E7, E9, F, and I rules. Use snake_case for modules, functions, variables, and test files; PascalCase for classes; and uppercase names for constants. Keep cross-module contracts in shared framework packages rather than importing another business module’s internals.
Testing Guidelines
Tests use pytest and follow test_*.py / test_* naming. Add focused unit tests for new logic and regression tests for fixed defects. Changes to workflows, schedules, manifests, runtime paths, or CLI behavior should include acceptance or boundary coverage. Avoid tests that require live credentials or mutate production services.
Commit & Pull Request Guidelines
Use short Conventional Commit subjects such as feat: consolidate legacy workflows. Keep commits scoped. Pull requests should explain behavior, list verification, link issues, and call out configuration or migration effects. Never commit secrets, cookies, tokens, .env files, or generated var/ contents.