社区指南

参与 SQLAlchemy 及其关联项目的指南。

虽然这些部分可能针对 SQLAlchemy 核心项目的开发者撰写，但各种指南，尤其是行为准则，适用于 SQLAlchemy 组织存储库下托管的所有项目。

开发

本节描述了在哪里可以找到有关开发的信息以及一些入门技巧。

开发社区

您在哪里可以找到 SQLAlchemy 的开发者？

SQLAlchemy 的开发者恳请所有参与这些渠道的人员在寻求或提供支持时尊重 行为准则。

  • Github 讨论
    • Github 讨论 论坛是最常见的 - 核心开发者会帮助用户解决各种问题。所有 SQLAlchemy 用户和第三方库作者都鼓励在这里寻求支持。
  • 实时交流
    • 开发讨论持续在 sqlalchemy/devel Gitter 房间中进行。此房间中的讨论面向对贡献代码、测试、文档或其他开发资源感兴趣的用户。此频道是 SQLAlchemy 贡献者当前首选的实时讨论媒介，并承载了 定期开发者会议。您可以通过 sqlalchemy/community Gitter 房间获得基于 Gitter 的支持；有关此内容的更多信息，请参阅 支持 页面。

定期开发者会议

核心开发者和贡献者会定期在 sqlalchemy/devel Gitter 房间中进行实时虚拟会议。此会议旨在每周定期举行，但可能会根据所需成员的可用性而有所变化。在每次会议之前，房间中会包含指向包含下次定期会议日期、时间和议程的文档的链接；目前，此链接出现在房间的“主题行”或“标题”中。这些会议及其记录对公众开放。鼓励对贡献代码、测试、文档或其他开发资源感兴趣的用户参加。

源代码访问

SQLAlchemy 的源代码使用 Git 进行版本控制。主要公共存储库位于 GitHub

拉取请求

拉取请求提交到 GitHub 存储库 https://github.com/sqlalchemy/sqlalchemy。一旦被接受审核，假设拉取请求是更改代码本身而不是仅仅更正文档问题，代码审核将在我们的 Gerrit 系统 https://gerrit.sqlalchemy.org 中进行，我们可以在其中审查、修改代码，并通过持续集成测试对其进行运行，这些测试具有高度的控制和协作能力。拉取请求将在 Gerrit 中关闭，并附带指向审核的链接。代码更改的拉取请求绝不会直接合并。

请注意 拉取请求指南，这些指南修改了源代码（例如，不仅仅是文档）。

  • 建议您在提交拉取请求之前在问题跟踪器中提交问题，尤其是对于重大更改。拉取请求经常出现以下情况：要么没有描述它们打算解决的问题，要么以不适当或次优的方式解决了问题。提前打开错误或功能问题将使我们能够在贡献者付出努力编写代码和测试之前，了解用例并讨论最佳方法。
  • 始终在代码更改中包含测试 - SQLAlchemy 不会在没有相应测试的情况下提交代码更改 - 每一行没有测试的代码本身就是一个错误。如果提交的拉取请求没有测试，则在编写测试之前不能合并。我们经常收到长度只有一行的拉取请求，但我们需要编写数十行代码来测试它，因为99% 的代码更改工作都是编写测试。请不要提交没有测试的单行 PR。对于您无法提供测试的代码更改，请仅提交 完整的错误报告。
  • 请针对拉取请求上的更改请求进行跟踪，并订阅 Gerrit 审核以接收评论。 - 针对未做出响应的更改请求的拉取请求将被关闭。
  • 请确保您已配置为运行当前的 开发环境 要求，这将有助于确保您的 PR 通过自动测试。

测试

对于希望开发即使是最小功能或修复的任何人都来说，一项关键任务是熟练地运行测试，并且在理想情况下能够编写测试。SQLAlchemy 拥有数千项测试，这些测试的重点从单元测试到集成测试不等，并且在多个 Python 版本和数据库后端上运行的完整持续集成运行超过二十万次独立测试。到目前为止，开发工作的最大范围（包括对现有代码库的开发以及实施任何新功能或修复时）是在编写完整测试。特定更改或功能的测试通常比实际行为代码多 5 到 10 倍。编写测试也可能比编写实际功能困难得多，通常需要针对目标行为的各种难以预测的变体，注入用于测试目的的行为，拦截生成的 SQL、事件或 DBAPI 消息元素。

测试使用 py.test 运行。有关运行测试的全面指南，请参阅文件 README.unittests，该文件存在于源代码分发版中。此文件详细说明了如何跨多个范围运行测试，包括如何针对特定数据库运行测试以及如何选择特定测试。

测试本身是在多年时间里编写的，其风格一直在演变。随着我们对方法的熟练程度和先进程度的提高，我们尝试将旧测试升级到新的风格，但仍有许多测试需要升级。我们当前首选的风格（请记住，我们许多测试肯定还没有达到这种风格）如下所示

  • 测试应坚持 PEP8。许多旧测试目前不符合 PEP8；我们欢迎在这方面提供新的帮助。
  • 一次测试一项内容。最好将一系列独立的断言分解为独立的测试方法，而不是将多个断言放在一个测试方法中。
  • 将每个测试的状态保持为测试夹具的本地状态。也就是说，如果一系列测试都针对特定的表结构，则测试夹具应该准备表元数据并将其与 self 或 cls 关联。测试套件具有标准夹具，这些夹具可以极大地帮助此过程，它们位于 test/lib/fixtures.py 中。
  • 如果不需要，不要针对数据库后端进行测试。许多类型的测试只需要确保渲染了特定的 SQL 字符串。我们有一套全面的夹具，允许捕获 SQL 字符串并在不需要任何数据库往返的情况下断言。

持续集成

SQLAlchemy 项目使用 Jenkins 进行持续集成。我们的只读 Jenkins 接口可在 https://jenkins.sqlalchemy.org 访问。

文档

文档使用 Sphinx 生成。如果新开发者愿意编写新文档或处理当前文档，添加新示例，修复错别字，改进文档之间的链接，则他们会非常有帮助。这也是项目中最重要、最困难的工作之一。与测试一样，创建良好的文档所花费的时间远大于记录的功能本身。对于大多数开发者来说，编写文档并不像编写实际代码那样有趣，但愿意且能够这样做的开发者对项目来说非常宝贵。

代码指南

我们希望扩展本节。目前，请记住一些关键内容

  • 尽可能地坚持 PEP8。我们的行宽为 78 个字符，我们倾向于在反斜杠而不是括号上换行；尤其是 SQLAlchemy 生成查询最容易通过反斜杠换行的方式阅读。
  • 只有当新功能具有在 Sphinx 下运行的关联文档时，才能添加新功能。
  • 任何功能或错误修复都永远不会在没有完整 单元测试 的情况下提交，测试范围应尽可能大。
  • 请确保您已配置为运行当前的 开发环境 要求，这将有助于确保您的 PR 通过自动测试。

开发环境

SQLAlchemy 项目最近在开发过程中标准化了一些约定，其中大多数可以通过正确配置的开发环境自动执行。

  • 源代码格式和其他实用程序使用 pre-commit 框架中的挂钩自动应用。`pre-commit` 可以通过运行 pip install pre-commit 安装。
  • 源代码使用 Python 软件基金会的 black 进行格式化。`black`可以通过运行pip install black进行安装，但在大多数情况下，`pre-commit`会自动安装它。

TLDR; 请确保在开始 Pull Request 的工作之前，您的环境中安装了 pre-commit。