### 开发者指南

pypdf 是一个库，因此它的用户是开发者。本文件并非面向用户，而是提供给希望参与 pypdf 开发的人。

---

## 安装依赖

```bash
pip install -r requirements/dev.txt
```

---

## 运行测试

请参阅 [使用 pytest 测试 pypdf](testing.md)。

---

## sample-files Git 子模块

引入 `sample-files` 子模块的原因是：我们希望保持 pypdf 仓库的体积小巧，同时也需要一个广泛的测试套件。这两个目标在某种程度上是相互矛盾的。

- `resources` 文件夹应包含一组核心示例，涵盖我们通常需要测试的大部分情况。  
- `sample-files` 文件夹可能包含更多边缘情况、更大文件尺寸下的行为，以及由不同 PDF 生成工具产生的文件。

若要获取 `sample-files` 文件夹，请执行以下命令：

```bash
git submodule update --init
```

---

## 工具：Git 和 pre-commit

**Git** 是一个用于版本控制的命令行工具。如果你不熟悉它，可以通过 [ohmygit](https://ohmygit.org/) 进行学习。

**GitHub** 是托管 pypdf 项目的服务平台。Git 是免费且开源的，而 GitHub 是微软提供的付费服务，但在许多情况下免费使用。

**[pre-commit](https://pypi.org/project/pre-commit/)** 是一个基于 git hooks 的命令行工具，用于自动执行代码检查和格式化等任务。这可以帮助你避免代码风格和质量问题。

执行以下命令以启用 pre-commit：

```bash
pre-commit install
```

完成后，每次运行 `git commit` 时，pre-commit 将自动执行。

---

## 提交消息规范

清晰的提交消息可以帮助他人快速理解提交的内容，而无需查看代码变更。提交消息的第一行用于 [自动生成 CHANGELOG](https://github.com/py-pdf/pypdf/blob/main/make_release.py)，因此格式应为：

```
PREFIX: 描述

详细内容
```

### 前缀说明

| 前缀   | 含义与描述                                                                 |
|--------|---------------------------------------------------------------------------|
| **SEC** | 安全性改进，通常用于修复可能导致无限循环的问题。                              |
| **BUG** | 修复 bug。如果有相关 issue，请在详细内容中添加 `Closes #123`，其中 123 为 GitHub issue 编号。建议编写回归测试（修复前失败，修复后通过）。用户代码的 bug 属于此类，测试代码或 CI 问题不算。 |
| **ENH** | 添加新功能！详细内容中说明功能的用途。                                       |
| **DEP** | 弃用功能。可以是标记某功能为“即将移除”或实际移除该功能。                       |
| **PI**  | 性能改进。例如生成的 PDF 文件大小的减少或处理速度的提升。                      |
| **ROB** | 稳健性改进，更好地处理损坏的 PDF 文件。                                       |
| **DOC** | 文档更新或改进。                                                           |
| **TST** | 添加或调整测试用例。                                                       |
| **DEV** | 改进开发者体验，例如调整 pre-commit 或 CI 配置。                             |
| **MAINT** | 维护工作。包括性能优化、重构代码等。                                         |
| **STY** | 代码风格改进。例如使代码风格更一致，或改善面向用户的错误信息。                 |

### 重要说明

前缀用于自动生成 CHANGELOG。每个 PR 必须有且仅有一个前缀。如果你认为多个前缀适用，请选择列表中靠前的一个。

## Pull Request 大小

**小型 Pull Request (PR)** 更受欢迎，因为它们通常更容易被合并。例如，如果你需要修复一些拼写错误、进行代码风格调整、添加新功能以及修复一个 bug，那么这可以拆分成 3 到 4 个独立的 PR。

每个 PR 必须是完整的。这意味着，如果你引入一个新功能，该功能必须在该 PR 中完成，并且包含针对该功能的测试。

---

## 基准测试

我们需要持续关注性能表现，因此设有一些基准测试。

请参阅 [py-pdf.github.io/pypdf/dev/bench](https://py-pdf.github.io/pypdf/dev/bench/) 了解更多。