概览
对代码和文档的所有更改都应 提交。 提交。
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/Issue #>.<Change Type>.rst
例如，修复 GitHub 问题 #42 的拉取请求将命名为 42.bugfix.rst`。如果拉取请求与特定的 问题相关联，则可以使用拉取请求编号来代替。您可能需要 创建拉取请求无变更注释，以获得分配的拉取请求编号，然后推送与该编号相关的更新。 编号，然后推送包含变更注释的更新，并使用新分配的拉取请求编号。 新分配的拉取请求编号。
更改说明的更改类型应为以下类型之一：
- 特征
- 错误修正
- 文档
- 删除
- 杂项
misc "类型是为不影响用户的更改保留的，不需要在发布说明中注明。
无需在发布说明中注明的更改。小的排版修正
文档中的小排版修正、CI 配置更新以及尚未正式发布的
尚未正式发布的功能的错误修复都属于
使用 misc 标记描述的功能。
变更说明应该是一行文字，从用户的角度提供一个高层次的 从用户角度对变更进行高度概括，而不是深层次的技术描述或实施细节。 技术描述或实施细节。它有别于 提交信息。提交信息描述了所做的工作，以便 未来的开发人员可以了解变更的原因。变更说明 是一种 "面向用户 "的说明，描述的是变更后的新功能 的新功能。把变更说明看作 变更注释是宣布变更的新闻稿，而不是提交说明。 提交说明。
例如，如果您修复了一个由日期处理引起的错误，那么提交信息或拉伸请求的描述可能会是 消息或拉动请求的描述可能是
在 DateWidget 验证链中添加了 MM-DD-YYYY 格式验证器。 链。
这将描述对实现所做的更改--对审查代码的人有帮助的细节。 这对审查代码的人很有帮助。然而，相应的 相应的变更注释可能是这样的
日期部件现在可以接受 US 格式的日期。
这描述了最终用户将体验到的功能变化。 用户将体验到的功能变化。用户无需了解任何 有关实现的任何信息。
代码风格
BeeWare的项目使用Pre-commit](https://pre-commit.com/)来自动遵守代码风格。 代码风格。这些检查在每个版本库的 .pre-commit-config.yaml "文件中定义，并自动 CI 中自动运行。 打开时，会在 [CI](/contributing/first-time/what-is-a/ci 中自动运行。
要在本地开发环境中在每次 git commit 时自动执行预提交检查，请运行 pre-commit install。
包括预先承诺检查：
- 黑色 确保 统一代码格式
- docformatter确保 文档字符串和注释的统一格式
- pyupgrade确保代码 使用最新的 Python 最佳实践
- isort确保统一的 "import 语句
- flake8检查常见的编码和语法问题 和语法问题
- 验证结构化文档（如 TOML 文件）的杂项检查，以及 删除不必要的空白
其他指导原则：
避免在注释中使用 "我们"，例如 "Loop over "而不是 "We loop over 过"
变量名、函数名和方法名使用下划线，而不是驼峰字母 名称
类名（或返回类名的工厂函数）使用 InitialCaps 类名）
Use Sphinx-style docstrings and PEP 257; type annotation with PEP 484 is optional but encouraged.
例如：
def function_name(param1: int, param2: str) -> bool： ""带有类型和 docstring 的示例函数。 :param param1：第一个参数。 :param param2：第二个参数。 :returns：返回值。为 True 表示成功，否则为 False。 """在测试文档说明中，说明每个测试 演示的预期行为。不要包含诸如 "测试 "或 "确保 确保 "之类的前言。
为晦涩难懂的问题保留票单引用，因为票单中的 文档或注释中不易描述的额外细节。 注释。在句子末尾包含票单编号，如 这样
def test_foo()： ""测试文档字符串看起来像这样 (#123456)."""