写一个好补丁

撰写不相关更改

获得一个声称修复 11 个古怪问题的补丁令人烦恼，关于该补丁的讨论和意见不同意它们中的 10 个算问题，或者认为这些问题中的 9 个已经用另一方式被修复了。然后，合并这一更改的人需要从成堆的源码中提取出单一的有趣补丁，而这样做产生许多额外的工作。

更可取的方式是，每个解决一个问题的 fix 应当在其自己的 patch/commit 中，有自己的描述/提交信息，说清楚这个 fix 修正的是什么，这样维护者或其他感兴趣的人可以有选择地应用所有改动。

另外，单独更改启用二等分要好得多，这样便于跟踪 issues 和将来的 regression。

文档

文档工作也许枯燥乏味；然而，需要有人来完成这项工作。如果在提交代码改动时能一并提交文档信息会让事情变得容易的多。请记得记录下方法、复杂的代码块，或用户可见的功能。

参见

为 Weblate 文档作贡献

测试用例

这些测试允许我们快速验证功能是否正如预想那样运转。为了保持这一状况并改进它，所有添加的新特性和功能都需要在测试套件中测试，每个新添加的特性都应至少获得一个有效测试用例，来验证其如文档中记录的那样工作。

参见

Weblate 测试套件与持续集成

提交说明

Git 提交应该遵守 Conventional Commits 规范。

类型检查

Any new code should utilize PEP 484 type hints. We are using mypy to check them because it has a Django plugin that makes type checking of Django apps practical.

New and changed code should not introduce new mypy failures where current Django typing support makes that practical. The code base is not yet completely covered by type annotations, and some Django constructs are difficult to annotate precisely. CI therefore enforces mypy only for selected modules and reports other findings separately.

编码标准和代码检查

代码应该遵循 PEP 8 coding guidelines and should be formatted using ruff 代码格式化程序。

要检查代码质量，你可以使用 ruff，其配置存储在 pyproject.toml 中。

强制所有这些的最简单方法是安装 prek。这是 Weblate 所用的 pre-commit 工具的第三方重新实现。它被包含在 pyproject.toml 中声明的开发依赖中，因此安装这些依赖让 prek 变得可用。

要手动检查所有文件，请运行：

uv run prek run --all-files

如果偏好原版 pre-commit 客户端，它使用来自 .pre-commit-config.yaml 的相同配置。

安全地写代码

在为 Weblate 编写任何代码时都应该考虑到 从设计上就是安全的这一原则。

AI 指南

在向项目贡献内容时，您同意我们照原样使用它，且您必须确保您被允许将它分发给我们。向我们提交改动代表您同意这些更改能够并应当被本项目采用，并在本项目许可证下再次分发。作者应明确知道确保没有未经许可的代码被提交至本项目的责任在于作者。

这无关是否使用 AI。

贡献拉取请求时，你理所应当应该始终确保提议的质量上佳，并尽了最大努力遵守我们的指南。基本的经验法则是如果某人可以指出贡献是在 AI 帮助下做出的，那么你有更多的工作要去做。

本项目可以接受在 AI 帮助下写出的代码，但这样的代码仍必须遵守代码标准，要编写清晰、有记录、有特性测试用例，并遵照所有我们拥有的常规要求。