社区指南

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

虽然这些章节可能是为核心 SQLAlchemy 项目的开发者编写的，但各种指南，尤其是行为准则，适用于 SQLAlchemy 组织仓库下托管的所有项目。

开发

本节介绍在哪里可以找到关于开发的信息以及一些入门技巧。

开发社区

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

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

  • Github 讨论区
    • Github 讨论区论坛是最常见的 - 核心开发者协助用户解决各种问题。鼓励所有 SQLAlchemy 用户和第三方库作者在此处寻求支持。
  • 实时通讯
    • 开发讨论每周都会在 sqlalchemy/devel Gitter 房间持续进行。此房间中的讨论旨在为对贡献代码、测试、文档或其他开发资源感兴趣的用户而设。此频道是 SQLAlchemy 贡献者当前首选的实时讨论媒介，并托管计划开发者会议。基于 Gitter 的支持可通过 sqlalchemy/community 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 版本和数据库后端上的完整持续集成运行超过二十万个单独的测试。到目前为止，无论是对于现有代码库还是对于正在实现的任何新功能或修复，最大的开发工作范围都在于编写完整的测试。特定更改或功能的测试代码行数通常是实际行为代码的五到十倍。它们也可能比实际功能更难编写，通常需要对目标行为进行各种难以预测的变体、注入行为以进行测试、拦截生成的 SQL、事件或 DBAPI 消息传递元素。

测试使用 py.test 运行。有关运行测试的综合指南，请参见源代码发行版中的文件 README.unittests。该文件详细解释了如何在多个范围内运行测试，包括如何针对特定数据库运行以及如何选择特定测试。

这些测试本身是在多年过程中编写的，并且在风格上不断发展。当我们变得更加熟练和先进时，我们尝试将旧测试升级到较新的风格，但仍然有很多测试需要升级。我们当前首选的风格如下，请记住，我们的许多测试当然尚未采用这种风格

  • 测试应坚持 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 框架中的钩子自动应用。可以通过运行 pip install pre-commit 来安装 `pre-commit`。
  • 源代码使用 Python 软件基金会的 black 进行格式化。可以通过运行 pip install black 来安装 `black`，但是 `pre-commit` 应该在大多数情况下自动安装它。

TLDR；在开始处理拉取请求之前，请确保您的环境中安装了 pre-commit。