获取 SQLAlchemy

修订版本

修订版本是最常见的发布系列，对于活跃的项目，每隔几周甚至更短的时间就会发布一次。修订版本应 **始终与任何项目完全兼容，以便在不进行任何更改的情况下将项目移至该版本，前提是给定特定主版本/次版本系列**。这意味着，如果一个项目使用 SQLAlchemy 的 1.2.3 版本，理想情况下，该项目应该能够直接升级到最新的 1.2.x 系列，例如 1.2.19，而无需升级到中间版本。

修订版本包括三种变更类别

• **错误修复** - 修订版本的主要目的是发布错误修复，而不会进行任何向后不兼容的变更。被认定为对向后兼容性风险过高的错误修复将改为推送到次版本中。
• **用例添加** - “用例”是一种介于“错误修复”和“功能”之间的变更类别，它们通常适用于对新数据库功能的支持。由于用户不断创建或请求新数据库功能，并且通常涉及特定数据类型或小型 SQL 语法，因此这些功能通常会添加到修订版本中，前提是它们不会破坏 SQLAlchemy 或 Alembic 迁移中的向后兼容性。较大的用例添加将在次版本中发布。
• **小型功能添加** - 由于修订版本的发布周期为每隔几周，而次版本的发布周期通常为至少一年或更长时间，因此不会对任何当前代码或 API 产生影响的功能添加通常会包含在修订版本中；一个例子是 在 ORM 加载程序选项上创建子选项的能力。

请注意，虽然修订版本是最保守和最频繁的发布流，但始终有可能引入意外的回归。建议项目在升级到任何 SQLAlchemy 组织软件的新版本时始终全面测试其软件，包括使用测试套件和/或暂存环境。

重要的次版本

SQLAlchemy 中的次版本实际上是“重大”事件，因为它们通常需要一年时间才能发布；对于相关项目，次版本可能发布频率较低。我们可能会将它们称为 **重要的次版本**，以表明它们是重大事件，但同时不将它们与“主版本”混淆，因为“主版本”通常指的是版本编号方案中最左边的数字。次版本的变化意味着该项目包含的变更 **通常在不先前已弃用的 API 和当前 Python 版本范围内向后兼容，但也存在一些非向后兼容的风险**，特别是在 SQLAlchemy 本身中；由于变更的性质，这种风险通常是不可避免的。

因此，“重要的次版本”对于 SQLAlchemy 本身来说并非真正“次要”，并且始终有一个 详细的迁移说明 部分，详细描述了可能需要识别的每个 API 调整和行为变更。对于其他项目，次版本通常指的是 Python 版本支持的变更，例如放弃对 Python 2.6 的支持，或者 Alembic 放弃对 SQLAlchemy 0.9 的支持；有关新增内容的概述，请参阅变更记录。

重要的次版本，特别是在 SQLAlchemy 本身中，将包括

• **主要新功能** - 新的 API 功能和能力，以及结构和性能改进，是 SQLAlchemy 本身和相关项目的每个次版本的一部分。这些添加通常完全向后兼容，但是由于它们通常会更改大量的内部代码，因此回归的风险更高，特别是在 SQLAlchemy 中；这些回归通常会在新次版本的最初几个修订版本中解决。与往常一样，下游应用程序应运行其测试套件并报告新次版本中的任何问题。

• **行为变更** - 大多数行为变更都很微妙，不太可能在一般情况下造成问题。但是，这些变更可能与依赖于先前错误行为或绕过旧行为（旧行为不再产生相同结果）的最终用户代码向后不兼容。一个典型的例子是以前没有正确引用或转义的 SQL 渲染，然后进行了修复；下游应用程序通常会通过手动应用引用来解决此问题，一旦 SQLAlchemy 修复了此问题，该引用就变得多余。此类变更的一个例子是 列级 COLLATE 关键字现在会引用排序规则名称，它会将引用添加到必须以区分大小写的形式指定的数据库排序规则名称。

  预计不会造成问题的行为变更仍然有记录，以防出现一些不可预见的问题；一个例子是 FOR UPDATE 子句在联接急切加载子查询中以及外部都被渲染¶，它修改了在包含联接急切加载的 SELECT 中渲染“FOR UPDATE”的方式。此变更对 MySQL 用户的影响最大，因为它绕过了已知的 MySQL 问题，并且会突然开始锁定联接急切加载中相关表中的表行，而在此前的特定后端上并非如此。

• **API 弃用** - SQLAlchemy 和相关项目尝试仅在次版本中添加新的弃用，而不是在修订版本中添加。任何已弃用的 API 应该尽可能多地发出DeprecationWarning当使用该 API 时。虽然这在旧版本中并不总是如此，但目标是仅在次版本中添加弃用，并且它们应该在使用时发出警告。这样做是为了让项目有整个次版本周期来迁移出旧的 API，并且使弃用易于识别。

• **删除先前已弃用的 API** - 在特定次版本中弃用的 API 可能会在下一个次版本中立即删除，尽管已弃用的 API 通常会在多个次版本中保留。在现代版本中，已弃用的 API 在整个特定次版本周期内使用时应发出警告。

主版本

主版本指的是项目的总体成熟度状态，这是一个多年状态。项目从 0 开始，例如 sqlalchemy-collectd-0.0.4，它表示从初始 Alpha 版本到长期稳定版本的成熟度范围，它认为主版本之间的每个次版本都可能发生重大变更。在主版本 1 中，项目被认为已成熟。主版本 2 及更高版本分别表示项目与 Python 2 到 Python 3 类似的重大变化。