python-workflow-delivery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Workflow and Delivery

Python工作流与交付

Overview

概述

Branch-to-PR execution discipline for Python work: validate, scope, and ship with confidence. Apply these defaults before opening or updating a PR.

These are preferred defaults for common cases, not universal rules. When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

Python工作的分支到PR执行规范：自信地验证、界定范围并交付代码。在创建或更新PR前遵循这些默认规范。

这些是针对常见场景的推荐默认规范，而非通用规则。若需偏离，请说明取舍方案及补偿控制措施（如测试、可观测性、迁移、回滚）。

When to Use

适用场景

Preparing a branch or PR for Python changes.
CI gate failures on lint, format, or test steps.
Lockfile or dependency conflicts during
```
uv sync
```
.
Commits that bundle too many concerns or are hard to review.
Uncertainty about which validation steps to run before merge.

When NOT to use:

Pure design or architecture decisions — see
```
python-design-modularity
```
.
Test strategy or fixture design — see
```
python-testing
```
.
Runtime operations or deployment — see
```
python-runtime-operations
```
.

为Python代码变更准备分支或PR时。
CI检查在lint、格式或测试步骤失败时。
执行
```
uv sync
```
时出现锁文件或依赖冲突时。
提交的代码包含过多无关内容，难以评审时。
不确定合并前需要执行哪些验证步骤时。

不适用场景：

纯设计或架构决策——请参考
```
python-design-modularity
```
。
测试策略或夹具设计——请参考
```
python-testing
```
。
运行时操作或部署——请参考
```
python-runtime-operations
```
。

Quick Reference

快速参考

Use the project-defined Python version first.
Use
```
uv
```
for environment and dependency workflow.
Run checks with
```
uv run ...
```
.
Keep scope small, reversible, and reviewable.

优先使用项目定义的Python版本。
使用
```
uv
```
管理环境和依赖工作流。
通过
```
uv run ...
```
执行检查。
保持代码范围小、可回滚、便于评审。

Validation Gate

验证检查

Run as required by project scope:

```
uv sync
```
```
uv sync --locked
```
```
uv lock --check
```
```
uv run ruff check .
```
```
uv run ruff format --check .
```
```
uv run pytest
```

Change-specific checks:

Dependency/lockfile changes:

uv run pytest scripts/test_pypi_security_audit.py -v

Async lifecycle changes: run
```
pyleak
```
diagnostics on representative async integration tests.

根据项目范围按需执行：

```
uv sync
```
```
uv sync --locked
```
```
uv lock --check
```
```
uv run ruff check .
```
```
uv run ruff format --check .
```
```
uv run pytest
```

针对特定变更的检查：

依赖/锁文件变更：执行

uv run pytest scripts/test_pypi_security_audit.py -v

异步生命周期变更：对代表性的异步集成测试运行
```
pyleak
```
诊断。

Common Mistakes

常见错误

Skipping
uv lock --check
— merging without verifying the lockfile matches
```
pyproject.toml
```
causes CI failures downstream.
Bundling unrelated changes in one commit — mixing refactors, features, and dependency bumps makes review slow and reverts dangerous.
Running
ruff check
but not
ruff format --check
— passing lint does not guarantee formatting; both gates matter.
Forgetting change-specific checks — dependency updates need the security audit; async changes need leak diagnostics. Generic
```
pytest
```
alone is not enough.

跳过
uv lock --check
—— 在未验证锁文件与
```
pyproject.toml
```
匹配的情况下合并代码，会导致下游CI失败。
在单个提交中捆绑无关变更 —— 将重构、功能新增和依赖升级混在一起会减慢评审速度，且回滚风险高。
仅运行
ruff check
而未执行
ruff format --check
—— 通过lint检查不代表格式合规；这两项检查都很重要。
忘记执行特定变更的检查 —— 依赖更新需要安全审计；异步变更需要内存泄漏诊断。仅运行通用的
```
pytest
```
是不够的。

Scope Note

范围说明

Treat these recommendations as preferred defaults for common cases, not universal rules.
If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

请将这些建议视为常见场景的推荐默认规范，而非通用规则。
如果默认规范与项目约束冲突或会导致更差的结果，请提出更合适的替代方案并解释原因。
若需偏离，请说明取舍方案及补偿控制措施（如测试、可观测性、迁移、回滚）。

Invocation Notice

调用说明

Inform the user when this skill is being invoked by name:
```
python-design-modularity
```
.

当按名称调用此技能时，请告知用户：
```
python-design-modularity
```
。

References

参考资料

```
references/workflow.md
```
```
references/branch-commit-scope.md
```

```
references/workflow.md
```
```
references/branch-commit-scope.md
```