概览

对代码和文档的所有更改都应以拉取请求的形式提交至项目的 GitHub 仓库。

Most projects have a dedicated contribution guide with details specific to that project, or specific types of contribution. This documentation can be found on Read the Docs. For example, Briefcase's documentation contains contribution guides for both code and documentation.

所有提交的内容均应遵守 BeeWare 行为准则。

更改说明

一些 BeeWare 项目，特别是 Briefcase 和 Toga，要求每个拉取请求都要提交一份变更说明。这些变更注释将会被编译在一起，生成新版本的发布说明。

BeeWare 使用 Towncrier 管理更改说明。

应在 changes 目录下创建变更注释文件，并按以下格式命名它：

<PR/问题 编号>.<变更类型>.rst

例如，修复 GitHub 问题 #42 的拉取请求将会被命名为 42.bugfix.rst。如果拉取请求不与任何特定的问题相关联，则可以使用拉取请求编号来代替。您可能需要先创建一个不包含变更注释的拉取请求，以获得分配的拉取请求编号，然后在 push 包含使用该编号的更改说明的更新。

更改说明的类型应为以下之一：

  • feature (功能)
  • bugfix (问题修复)
  • doc (文档)
  • removal (删除)
  • misc (杂项)

misc 类型是为不影响用户的且无需在发布说明中注明的更改保留的。文档中的小的排版修正、CI 配置更新以及尚未正式发布的功能的错误修复都使用 misc 标记描述。

变更说明应该是一行文字，从用户角度对变更进行高度概括，而不是深层次的技术描述或实施细节。它有别于提交信息 (commit message)。提交信息描述变更做了什么，以便未来的开发人员了解变更的原因。变更说明是一种面向用户的说明，描述的是变更后的新功能。把变更说明看作宣布变更的新闻稿，而不是提交说明。

例如，如果您修复了一个由日期处理引起的错误，那么提交信息或拉取请求的描述可能会是：

在 DateWidget 验证链中添加了 MM-DD-YYYY 验证器。

这将描述对实现所做的更改--对审查代码的人有帮助的细节。 这对审查代码的人很有帮助。然而，相应的 相应的变更注释可能是这样的

Date widgets can now accept dates in US format.

这描述了最终用户将体验到的功能变化。用户无需了解任何与实现相关的任何信息。

代码风格

BeeWare 的项目使用 Pre-commit 来自动保证代码风格遵守。这些检查在每个版本库的 .pre-commit-config.yaml 文件中定义，并在拉取请求打开时自动在 CI中运行。

要在本地开发环境中在每次 git commit 时自动执行预提交检查，请运行 pre-commit install。

包括以下提交前 (pre-commit) 检查：

  • Black 以确保统一代码格式
  • docformatter 以确保文档字符串和注释的统一格式
  • pyupgrade 以确保代码使用最新的 Python 最佳实践
  • isort 以确保统一的 import 语句
  • flake8 以检查常见的编码和语法问题
  • 验证结构化文档（如 TOML 文件）的杂项检查，以及删除不必要的空格

其他指导原则：

  • 避免在注释中使用 “we”（我们）, 例如 "Loop over" 而不是 "We loop over"

  • 变量名、函数名和方法名使用下划线，而不是 camelCase

  • 类名（或返回类的工厂函数）应使用 InitialCaps

  • 使用 Sphinx 格式的文档字符串 (docstrings) 且遵循 PEP 257；使用 PEP 484 格式标注类型是可选但被鼓励的。

    例如：

    def function_name(param1: int, param2: str) -> bool:
    """Example function with types and a docstring.

    :param param1: The first parameter.
    :param param2: The second parameter.

    :returns: The return value. True for success, False otherwise.
    """

  • 在测试中的文档字符串 (docstring) 中，说明每个测试演示的预期行为。不要包含诸如“测试”或”确保”之类的前言。

  • 只在有晦涩难懂的问题时，且当记录单中有不可简单的在文档字符串或注释中描述的更多细节时，才使用记录单引用。在句子末尾像如下这样包含记录单编号：

    def test_foo():
    """A test docstring looks like this (#123456)."""

  • 除非另有说明，请遵循 PEP 8（特别注意第 2 节的内容）。