代码库开发指南#

代码规范#

写出好的代码不仅在于你写了什么，更在于你是如何写的。在持续集成测试期间，会有多个工具来检查您的代码是否存在风格错误。良好的编程风格是提交代码到 Xinference 的要求之一。

此外，不要对代码进行突然的更改，这可能会导致大量用户代码出现问题。所以，我们需要尽可能地保持向后兼容，以避免大规模的故障。

自动修复格式错误#

此外，持续集成将使用 pre-commit hooks 运行诸如 black、flake8、isort 等代码格式检查工具。任何由这些检查生成的警告都将导致持续集成失败。因此，建议在提交代码之前自行运行这些检查。可以通过在 Xinference 仓库的根目录下安装 pre-commit 来完成这一操作：

pip install pre-commit

然后执行命令：

pre-commit install

安装好了以后就能确保每次提交更改时都会自动执行所有样式检查，无需手动逐个运行。此外，使用 pre-commit 也能让您更轻松地在我们的代码检查发生更改的时候保持同步。

请注意，如果需要，您可以通过使用 git commit --no-verify 命令来跳过这些检查。

如果您不想将 pre-commit 作为工作流程的一部分，仍然可以运行如下命令来使用它进行检查：

pre-commit run --files <files you have modified>

而不需要事先执行 pre-commit install。

如果您想在所有最近提交的文件上运行检查，您可以使用以下命令：

pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files

而不需要事先执行 pre-commit install。

备注

您可以考虑定期运行 pre-commit gc 命令来清理不再使用的存储库。

备注

如果您安装了冲突的 virtualenv 版本，可能会导致错误 - 可以参考 这里 。

此外，由于 virtualenv 中的一个 错误 ，如果您使用 conda，可能会遇到问题。要解决这个问题，您可以将 virtualenv 降级到版本 20.0.33。

向后兼容#

请尽量保持向后兼容性。如果您认为必须进行更改，请在拉取请求中说明清楚原因。同时，在更改方法签名时要小心，并在需要时添加弃用警告。此外，为弃用的函数或方法添加弃用的 sphinx 指令。

同时你还需要

  1. 编写一个新的测试样例，在调用带有弃用参数时会发出警告。

  2. 更新所有 Xinference 现有的测试样例和代码，以使用新的参数。

类型提示#

Xinference 强烈鼓励使用 PEP 484 风格的类型提示。新的开发应包含类型提示，并且对现有代码进行注释的拉取请求也是可以接受的！

测试驱动开发#

Xinference 非常重视测试，并强烈鼓励贡献者采用 测试驱动开发(TDD) 。这种开发过程 "依赖于非常短的开发周期的重复：首先，开发者编写一个（初始为失败的）自动化测试样例来定义所需的改进或新功能，然后用最少的代码来通过该测试。"因此，在实际编写任何代码之前，您应该编写您的测试样例。通常，测试样例可以从原始的 GitHub issue 中获取。然而，值得考虑额外的情况并编写相应的测试样例。

在将代码推送到 Xinference 之后，经常会要求添加测试样例。因此，养成提前编写测试样例的习惯非常重要，这样就不会出现问题。