企业官网建设流程全解析

Pydantic 贡献指南：从环境搭建、Issue 提交到 PR 合并的完整开发流程

【免费下载链接】pydanticData validation using Python type hints项目地址: https://gitcode.com/GitHub_Trending/py/pydantic

本文以仓库根目录的 CONTRIBUTING.md 为骨架，结合 Makefile、pyproject.toml、pydantic/version.py、tests/test_docs.py 等源码与配置，系统梳理 Pydantic 项目的贡献全流程。无论你是想提交第一个 Issue、修复文档中的错别字，还是为验证引擎贡献 Rust 代码，读完本文都能掌握：如何正确报告问题、如何一键搭建开发环境、如何运行测试与 lint、如何构建文档并遵循文档风格规范，以及项目对 AI 辅助提交的明确态度。

快速上手（tl;dr）

Pydantic 贡献流程的核心只有三条命令，本文后续所有小节都是对这三条命令的展开说明：

# 修复代码格式（自动格式化与 lint 修复） make format # 运行测试与 lint（默认目标 all：lint + typecheck + codespell + testcov） make # 构建文档站点 make docs

从 Makefile 可以看到.DEFAULT_GOAL := all，因此直接执行make等价于make all，会依次运行 Python/Rust lint、类型检查、拼写检查与带覆盖率统计的测试。make help可以列出全部可用目标。

提交 Issue：如何让维护者高效地帮助你

问题（Question）、功能请求（Feature Request）和缺陷报告（Bug Report）都通过官方的 discussions 或 issues 入口提交。如果涉及安全漏洞，请走安全策略流程，而不是公开提交 Issue。

为了让维护者能快速定位问题，请在 Issue 中务必附上 Pydantic 的完整版本信息，运行以下命令并将输出粘贴到 Issue 里：

python -c "import pydantic.version; print(pydantic.version.version_info())"

如果你使用的是v2.0 之前的 Pydantic，请改用：

python -c "import pydantic.utils; print(pydantic.utils.version_info())"

从源码看，pydantic/version.py 中的version_info()会输出一整套诊断信息，包括：pydantic version、pydantic-core version、pydantic-core build、python version、platform，以及 email-validator、fastapi、mypy、pydantic-settings、pyright、typing_extensions 等相关包的版本，还会通过 pydantic/_internal/_git.py 读取当前 git commit 短哈希。这些信息能帮助维护者瞬间判断问题是否由版本不匹配（例如 pydantic-core 与 pydantic 版本不兼容）引起。

注意：pydantic-core与pydantic的版本是严格绑定的，pydantic/version.py 中的check_pydantic_core_version()会校验pydantic_core.__version__是否等于_COMPATIBLE_PYDANTIC_CORE_VERSION（当前为 2.48.0），不一致时直接抛错。所以报告版本信息时两者都需包含。

除非你确实无法安装 Pydantic，或者确定版本信息与问题无关，否则请尽量总是附上这段输出。

提交 Pull Request：先讨论，再动手

Pydantic 对 PR 有一个明确的约定：除非你的改动是琐碎的（typo、文档微调等），否则请先创建一个 Issue 讨论改动方案，再创建 Pull Request。任何"未分配给你就修复既有 Issue 的 PR"会被自动关闭。

Pydantic V1 已进入维护模式

一个需要特别留意的背景：Pydantic v1 处于维护模式，只接受 bug 修复与安全修复，新特性一律面向 v2 开发。若要为 v1 提交修复，PR 的目标分支应为1.10.X-fixes。

这与仓库目录结构一一对应：仓库同时维护了 pydantic/v1/（v1 兼容命名空间）与根级 pydantic/ 模块，而pydantic-core（Rust 实现）是 v2 的核心引擎。

AI 使用政策：欢迎使用，但必须"真正理解"

Pydantic 官方欢迎使用 AI 辅助贡献，但有一个硬性前提：贡献者必须证明自己完全理解所提交的代码。项目保留在任何时候、不做进一步说明地关闭任意 PR 的权利，包括但不限于以下情况：

• 贡献不满足项目质量标准的；
• 作者疑似在多个仓库间批量刷 PR（spam）；
• PR 描述是 AI 生成的且内容混乱、无意义。

上述行为甚至可能导致永久封禁。这条政策值得所有"AI 时代"的贡献者认真对待：AI 可以是效率工具，但贡献者需要对代码的正确性与合理性负全责。

开发环境搭建

前置条件

开发 Pydantic 需要以下工具，版本要求以当前仓库为准：

之所以需要 Rust，是因为 Pydantic v2 的核心验证引擎 pydantic-core 是 Rust 实现（通过 PyO3 暴露给 Python），例如 pydantic-core/src/validators/ 下的int.rs、string.rs、union.rs等即对应 Python 侧的类型验证逻辑。

安装与初始化

# Clone your fork and cd into the repo directory git clone git@github.com:<your username>/pydantic.git cd pydantic # Install UV and pre-commit curl -LsSf https://astral.sh/uv/install.sh | sh uv tool install pre-commit # Install pydantic, dependencies, test dependencies and doc dependencies make install

make install在 Makefile 中实际执行：

install: .uv uv sync --frozen --all-groups --all-packages --all-extras uv pip install pre-commit uv run pre-commit install --install-hooks

即：用uv sync按uv.lock锁定文件安装所有依赖组、所有包、所有 extras（开发、文档、lint、类型检查等，见 pyproject.toml 中的dev、docs、linting、typechecking、build等依赖组），并安装配置 pre-commit 钩子。仓库根目录的 .pre-commit-config.yaml 定义了提交前自动执行的钩子：禁止直接向 main 分支提交、YAML/TOML 语法检查、文件末尾换行修复、尾随空格清理、codespell 拼写检查、markdownlint、yamlfmt，以及本地的make lint-python、make lint-rust和 Pyright 类型检查。

创建分支并开始改动

# Checkout a new branch and make your changes git switch -c my-new-feature-branch # Make your changes...

运行测试与 Lint

本地开发的核心循环如下：

# Run automated code formatting and linting make format # Pydantic uses ruff, an awesome Python linter written in Rust # Run tests and linting make

make format（Makefile）会依次执行：ruff check --fix自动修复 Python 问题、ruff format统一代码风格、cargo fmt格式化 Rust 代码——也就是说一次 format 同时覆盖 Python 与 Rust 两侧。

make（即make all）则串起四类检查：

1. lint：lint-python（ruff 检查 + 格式校验）与lint-rust（进入pydantic-core执行其 lint）；
2. typecheck：通过 pre-commit 运行 Pyright 类型检查；
3. codespell：拼写检查；
4. testcov：运行测试并生成 coverage HTML/lcov 报告。

此外，Makefile 还提供了若干更细粒度的目标：

• make test：运行全部测试（跳过类型检查器集成测试），NUM_THREADS控制并行线程数（默认 1）；
• make testcov：测试 + 覆盖率报告；
• make test-no-docs：除文档测试外全部测试；
• make test-mypy/make test-typechecking-pyright/make test-typechecking-mypy/make test-typechecking-pyrefly：分别跑 mypy 集成测试与三类类型检查器的 typechecking 集成测试；
• make benchmark：启用基准测试；
• make test-pydantic-settings/make test-pydantic-extra-types：用当前版本的 pydantic 跑关联生态项目的测试，用于早期发现回归；
• make clean：清理缓存与构建产物。

构建与更新文档

如果你修改了文档，或者修改了函数签名、类定义、docstring（这些会进入 API 文档），必须确保文档能成功构建。文档基于 Material for MkDocs 构建，配置见 mkdocs.yml，API 文档由 mkdocstrings 从 docstring 生成。

# Build documentation make docs # You can also use `uv run mkdocs serve` to serve the documentation at localhost:8000

make docs实际执行uv run mkdocs build --strict（Makefile）。注意--strict意味着任何警告都会导致构建失败，mkdocs.yml 中validation配置将所有潜在问题（遗漏文件、绝对链接、未识别链接、锚点）都提升为 warn 级别，倒逼文档质量。

文档支持社交预览图（social previews），依赖mkdocs-material[imaging]。如果 imaging 插件导致构建失败，一个实用的排查办法是：注释掉mkdocs.yml中的social插件行后再执行make docs。

非发布周期的文档更新流程

项目每个 minor 版本发布时推送一份新版文档，每次向main提交则会更新dev路径。如果你在非发布周期修改了文档、并希望改动同步到latest，需要走docs-update分支流程：

1. 先向main开 PR 提交文档改动；
2. PR 合并后，检出docs-update分支，确保其与最新 patch release 标签（例如v2.9.2）同步；
3. 从docs-update检出新分支，将你的改动 cherry-pick 上去；
4. 推送并针对docs-update开 PR；
5. PR 合并后，新文档会被自动构建并部署。

维护者捷径：作为维护者可以跳过第二个 PR，直接把改动 cherry-pick 到docs-update分支。

提交与发起 PR

完成改动后，提交并推送你的分支，然后创建 Pull Request。请遵循 PR 模板，尽可能完整填写：链接相关 Issue，并描述改动内容。当 PR 准备好接受评审时，在评论区留言"please review"，维护者会尽快处理。

文档风格规范

代码文档（docstring）

所有模块、类定义、函数定义、模块级变量都必须使用符合规范的 docstring 进行文档化。Pydantic 采用Google 风格 docstring，并遵循 PEP 257 规范。Ruff 会自动 lint docstring，make format可自动修复大部分问题；当 Google 风格与 Ruff 规则冲突时，以 Ruff 的提示为准。

类属性与函数参数采用"name: description"格式描述；返回类型只需写描述（类型由签名推断）。

class Foo: """A class docstring. Attributes: bar: A description of bar. Defaults to "bar". """ bar: str = 'bar'

def bar(self, baz: int) -> str: """A function docstring. Args: baz: A description of `baz`. Returns: A description of the return value. """ return 'bar'

两条额外的约定：

• 类属性写在类 docstring 中；实例属性以 "Args" 形式写在__init__的 docstring 中；
• docstring 中可以包含示例代码，但示例必须是完整、自包含、可运行的（可参考pydantic.functional_validators.AfterValidator的写法）。

文档正文风格

文档整体应保持友好、平易近人的语气，在完整的前提下尽量简洁。鼓励代码示例，但要短小精悍；每个示例必须是完整、自包含、可运行的。优先使用 print 输出而非裸 assert（除非测试对象没有有用的 print 输出，此时 assert 也可以）。

文档示例会被测试

Pydantic 的单元测试会运行文档中的所有代码示例，因此示例必须正确且完整。这一点在 tests/test_docs.py 中有直接体现：

• test_docstrings_examples扫描整个pydantic/源码目录（含 pydantic/_internal、pydantic/experimental 等），逐个执行 docstring 中的示例；
• test_docs_examples扫描docs/目录下的所有 Markdown 文档，提取并运行其中的代码块；
• 执行时通过time_machine冻结系统时间，保证调用datetime.now()的示例输出确定可复现；
• 还配套test_error_codes、test_validation_error_codes等测试，校验文档中记录的 Usage 错误码、验证错误码与源码中的错误码集合完全一致。

新增代码示例后，可以用下面的命令运行文档测试，并自动更新示例的格式化与输出：

# Run tests and update code examples pytest tests/test_docs.py --update-examples

同时调试 Python 与 Rust

如果你同时接触pydantic（Python）与pydantic-core（Rust），很可能需要跨语言联合调试——例如在 Python 侧调用验证器时，单步跟踪到 Rust 实现内部。CONTRIBUTING.md 提供了一段在 VSCode 中完成 Python/Rust 联合调试的视频教程（其他 IDE 步骤类似），核心思路是同时附加 Python 调试器与 Rust 调试器（LLDB/CodeLLDB），在 Python 调用pydantic_core的边界处设置断点，从而贯通两层调用栈。仓库中 pydantic-core 的Cargo.toml与pydantic_core/core_schema.py是理解两层边界的良好起点。

为你的项目添加 Pydantic 徽章

如果你的项目使用了 Pydantic，可以在 README 中挂一个 Pydantic 徽章。徽章的 endpoint 数据源就存放在仓库中：docs/badge/v1.json 与 docs/badge/v2.json。

Markdown 方式（直接粘贴到 README.md）：

[![Pydantic v1](https://img.shields.io/endpoint?url=<v1.json 的 raw 地址>)](https://pydantic.dev) [![Pydantic v2](https://img.shields.io/endpoint?url=<v2.json 的 raw 地址>)](https://pydantic.dev)

reStructuredText 方式（适用于 Sphinx 系文档）：

.. image:: https://img.shields.io/endpoint?url=<v1.json 的 raw 地址> :target: https://pydantic.dev :alt: Pydantic .. image:: https://img.shields.io/endpoint?url=<v2.json 的 raw 地址> :target: https://pydantic.dev :alt: Pydantic

HTML 方式：

<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=<v1.json 的 raw 地址>" alt="Pydantic Version 1" style="max-width:100%;"></a> <a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=<v2.json 的 raw 地址>" alt="Pydantic Version 2" style="max-width:100%;"></a>

三种方式的差异仅在于渲染载体：Markdown 用于 GitHub README，reStructuredText 用于 Sphinx 文档，HTML 用于任意网页。

加入第三方测试套件

为了在开发早期发现回归，Pydantic 会使用 Pydantic 对多个第三方开源项目持续跑测试。如果你的项目重度依赖 Pydantic，并符合以下部分或全部条件，可以申请加入：

• 项目处于活跃维护状态；
• 项目使用了 Pydantic 的内部机制（例如依赖BaseModel元类、typing 工具）；
• 项目足够流行（小项目也可能入选，取决于 Pydantic 的使用方式）；
• 项目 CI 足够简单，可以移植到 Pydantic 的测试工作流中。

如果满足条件，可以提交一个 feature request 讨论纳入事宜。这一机制的工程价值在于：pydantic-core每次迭代都可能有行为变化，第三方项目的测试覆盖能提前暴露兼容性风险，避免破坏下游生态。

写在最后：一份可执行的贡献自检清单

结合 CONTRIBUTING.md 全文，提交贡献前请过一遍以下清单：

1. 报 Bug：运行python -c "import pydantic.version; print(pydantic.version.version_info())"，把完整版本信息附进 Issue；安全漏洞走安全策略渠道；
2. 提 PR：非琐碎改动先建 Issue 讨论；未分配的任务不要抢修；v1 修复选1.10.X-fixes分支；
3. AI 辅助：确保自己完全理解提交的每一行代码，PR 描述清晰连贯；
4. 环境：满足 Python 3.10–3.14、uv、git、make、Rust 前置条件；make install一键装齐所有依赖与 pre-commit 钩子；
5. 质量：make format修格式，make跑全量测试与 lint，make docs用 strict 模式验证文档可构建；
6. 文档：Google 风格 docstring，示例完整可运行，新增示例后用pytest tests/test_docs.py --update-examples校验并刷新输出；
7. 提交：遵循 PR 模板、链接相关 Issue，就绪后评论 "please review"。

Pydantic 的核心哲学是"数据验证靠类型注解"，而其工程流程的核心哲学则是：让贡献的每一步都可运行、可验证、可追溯——从version_info()的精准诊断，到被测试自动执行的文档示例，再到 Rust/Python 联合调试，都服务于这一目标。

【免费下载链接】pydanticData validation using Python type hints项目地址: https://gitcode.com/GitHub_Trending/py/pydantic