Haystack 处于积极开发阶段，这意味着功能被添加、弃用或删除的频率相当高。此政策旨在最大程度地减少这些变更对现有用户和部署的影响。它提供了一个清晰的时间表，并概述了在升级到新 Haystack 版本之前所需的步骤。

重大变更定义

当以下情况发生时，即发生重大变更：

• 组件被移除、重命名或 Python 导入路径被更改。
• 参数被重命名、移除或从可选更改为强制。
• 添加了新的强制参数。

现有部署可能会中断，并且该变更被视为重大变更。将变更声明为重大的决定与其潜在影响无关：尽管该变更可能仅影响使用特定 Haystack 功能的应用程序的一小部分，但仍会将其视为重大变更。

以下情况不被视为重大变更：

• 添加了新功能（例如，新组件）。
• 组件、类或实用函数获得了一个新的可选参数。
• 现有参数从强制更改为可选。

现有部署不受影响，并且该变更被视为非重大变更。发布说明将提及该变更，并可能提供升级路径，但升级 Haystack 不会破坏现有应用程序。

版本控制

Haystack 版本用三个由点分隔的数字标记，例如，2.0.1。每个数字都有特定含义：

• 2 是主版本号
• 0 是次版本号
• 1 是补丁版本号

📘

尽管相似，但 Haystack **不**遵循 语义化版本控制 的原则。请继续阅读以了解区别。

给定一个类型为MAJOR.MINOR.PATCH 的 Haystack 版本号，您应该预期：

1. 对于主版本号更改：根本性的、不兼容的 API 更改。在这种情况下，您很可能需要一个迁移过程才能更新 Haystack。主版本发布每年不超过一次，更改会有详细记录，并提供迁移路径。
2. 对于次版本号更改：可能不向后兼容的功能的添加或删除。大多数情况下，您可以无缝升级 Haystack 安装，但请务必参考 发布说明 获取指导。已弃用的组件是次版本发布中最常见的重大变更。
3. 对于补丁版本号更改：错误修复。您可以安全地将 Haystack 升级到新版本，而无需担心您的程序会中断。

现有功能的弃用

Haystack 力求健壮。为了实现这一点，我们通过删除不再使用的旧功能来清理代码。这有助于我们维护代码库、提高安全性并使一切更易于顺畅运行。在删除功能、组件、类或实用函数之前，我们会经过一个称为弃用的过程。

主版本或次版本（但不是补丁版本）可能会弃用先前版本中的某些功能，您应该预期：

• 如果在 Haystack 版本X.Y 中弃用了一项功能，该功能将继续工作，但 Python 代码将发出警告，详细说明为升级而应采取的步骤。
• 在 Haystack 版本X.Y 中弃用的功能将在 HaystackX.Y+1 中移除，为受影响的用户提供大约一个月的升级准备时间。

示例

为了澄清这个过程，这里有一个例子：

在某个时候，我们决定移除一个FooComponent，并在 Haystack 版本2.99.0 中将其宣布为弃用。以下是将会发生的情况：

1. 在 Haystack2.99.0 版本中，FooComponent 照常工作，但使用该组件会引发代码中的FutureWarning 消息。
2. 在 Haystack 版本2.100.0 中，我们从代码库中移除了FooComponent。尝试使用它会导致错误。

停止集成

当现有功能被更改或移除时，集成会经历与 Haystack 在本页详细介绍的相同的弃用过程。重要的是要注意，集成是独立的，并使用自己的包分发。在某些情况下，可能会发生一种特殊的弃用形式，即集成被停止，随后从核心集成存储库中移除。

为了让我们的社区有机会接管集成并继续维护，然后在被停止之前，核心集成会逐渐经历不同的状态，如下所述：

• 暂存
  • 集成的源代码从main 分支移至核心集成存储库的特殊staging 分支。
  • 从 Haystack 文档网站中移除文档页面。
  • 核心集成存储库的主 README 显示免责声明，解释如何从社区采用该集成。
  • 移除集成磁贴（集成维护者可以稍后重新添加）。
  • PyPI 上的集成包仍然可用。
  • 开始为期 3 个月的宽限期。
• 已采纳
  • 社区中的一个组织或个人同意接管暂存集成的所有权。
  • 采纳者创建自己的存储库，并且停止的集成的源代码将从staging 分支中移除。
  • PyPI 包的所有权转移给新的维护者。
  • 采纳者将在 haystack-integrations 中创建一个新的集成磁贴。
• 已停止
  • 如果在宽限期结束时没有人采纳暂存集成，则其源代码将从staging 分支中移除。
  • PyPI 包的集成不会被移除，但也不会再更新。