> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/api-can-kao/version-support-agreement.md).

# 版本支持协议

版本支持协议

本文档描述了同时适用于 Creator Hub 中的场景编辑器和脚本框架（ `@dcl/sdk` 包）的版本控制策略。

该版本控制策略的目标是，在 Decentraland Foundation 的 SDK 团队与内容创作者之间建立一份契约，明确预期，并让内容创作者能够据此规划工作。

## 定义

* *版本号* ——用于公开可用的软件版本的唯一标识符。该标识符由一个 *主版本* 号和一个 *次版本* 号组成，中间以点分隔（例如 7.2）。
* *版本系列* ——所有主版本相同的版本构成一个系列。若版本 A 与版本 B 属于同一系列，且 A 的次版本号高于 B，则称版本 A 是版本 B 的 *后继版本* （例如，7.11 是 7.10 的后继版本）。
* *破坏性变更* ——一种会迫使用户更改其代码或资源，以使其继续正常运行的变更。例如，某个属性更改了名称，这会迫使用户在代码中每次使用该属性时都要修改属性名。
* *非破坏性变更* ——一种不需要用户采取任何操作的变更。用户的代码和资源的行为与属性保持不变。
* *稳定版本* ——一种禁止其所有后继版本出现破坏性变更的版本（这些后继版本也都被视为稳定版本）。任何破坏性变更都必须仅通过创建新的版本系列并递增主版本号来引入，不过请参见“ [破坏性变更](#breaking-changes) ”一节中的注意事项。非破坏性变更通过递增次版本号来体现。
* *不稳定版本* ——一种允许其后继版本出现破坏性变更的版本。破坏性变更可以通过递增次版本号来引入。

## 支持策略

在每个稳定版本系列中，Decentraland Foundation 仅支持最新的次版本。在任何给定时间，最多只应有两个受支持的系列。

例如，如果 6.x 系列的最新次版本是 6.11，而 7.x 系列的最新次版本是 7.3，那么内容创作者应当使用 6.11 或 7.3 来开发他们的场景。使用 6.10 或更早版本开发并发布的场景大概率仍可正常运行，玩家也仍然可以体验它们。不过，如果这些较旧的场景出现任何问题，必须先将其更新到受支持的版本，只有在更新后问题仍然存在时，才会对该问题进行调查。

场景编辑器会自动将同一版本系列内所有场景的脚本包更新到最新版本，从而确保所有开发者在开发场景时使用最新受支持的版本。

## 功能开发

新功能只会发布到正在开发中的最新版本中。一旦开发团队开始着手一个新的版本系列，仍在受支持范围内的旧版本系列将只会收到主要错误修复，不会再实现其他新功能。

## 破坏性变更

破坏性变更应当只出现在重大版本发布中。同一版本系列的稳定次版本发布中不应出现破坏性变更，除非在紧急情况下且没有其他办法处理。次版本发布中的破坏性变更是一种极端措施，开发者会不惜一切代价避免。新的次版本发布会扩展现有语法的能力，但绝不应改变既有语法的输出，修复漏洞的情况除外。

### 孤立变更

在极少数情况下，如果只会给一小部分用户带来不便，采取一个小范围、孤立的破坏性变更可能更合适。（创建一个新的主版本会给所有用户带来不便。）在这种情况下，SDK 可能会弃用某项功能，但必须在合理时间内继续支持它。

### 紧急变更

在某些特殊情况下，例如出于安全考虑或监管要求，不论稳定性级别如何，任何功能都可以以破坏性方式进行更改，在这些情况下也不会承诺弃用过渡期。

## 稳定与不稳定发布

### Alpha

每当引入一个新的主版本发布时，前几个次版本发布可能会被标记为不稳定 **alpha** 版本。在 alpha 发布中必须允许并预期存在破坏性变更，用户不应期待其稳定性。

开发者可以自由地使用这些 alpha 版本进行实验，但不鼓励使用不稳定的 alpha 版本发布内容，因为无法保证在后续更改后内容仍能正常工作。此时也不建议开始大规模、复杂的迁移，因为在下一个稳定版发布前可能还需要进一步修改。

### Beta

一旦某个版本系列达到一定成熟度，便会提供 **beta** 发布版。beta 发布版被视为已完成并准备好声明为稳定版本，但前提是经过公开测试。

beta 版本系列应尽可能保持稳定；不过，它们仍被允许随时间变化。这些变化应尽量少，但也可以包含破坏性变更。只有在经过合理的弃用期之后，才能引入破坏性变更，以便给内容创作者机会迁移其场景。该弃用期必须在引入破坏性变更时一并定义。

beta 版本系列只能在 beta 状态停留有限时间，该时长会在标记为 beta 时指定。如果在这段时间内未发现问题，则应晋升为稳定版本。具体时长可视情况而定，但一个较好的经验法则是 90 天。

使用 beta 版本语法编写的内容，应当容易迁移到该系列的后续版本。尽管如此，仍不建议用 beta 版本来开发大型活动内容，因为此时测试仍在进行中，出现漏洞的可能性较大。

### 稳定

一旦 beta 期限结束且未出现重大问题，该版本系列就被视为 **稳定** ，除新增功能外，语法不应再有进一步变化。从这一点开始，该版本被视为所有开发者都推荐并鼓励使用的选项。

稳定版本系列在其整个生命周期内都必须得到完全支持。除下文所述的注意事项外，不得有破坏性变更。

## 稳定发布中的不稳定功能

某次发布中的特定功能可能与整次发布的稳定性级别不同。这可能是因为该功能是最近才引入的，仍需要更多测试；也可能是因为它注定很快会被替换。

例如，在 SDK 框架的一个已经稳定的发布版中，可以将一种新的组件类型作为 alpha 引入，因为该组件可能仍需要自己的测试周期。之后它可以按照上文所述的版本控制流程，依次从 alpha、beta 过渡到 stable。

任何稳定发布中不被视为稳定的功能，都应在文档中明确标注为此类。使用不稳定功能的创作者必须意识到，该功能可能会发生破坏性变更。任何破坏性变更都会清楚地进行沟通，包括迁移指南，并且会留出一段过渡期，供创作者调整其场景代码。

## 我们会支持稳定版本系列多久？

一旦新的版本系列变为稳定版（7.x），团队会承诺在接下来的几个月内继续支持上一版本（6.x）（主要是错误修复），以便为创作者留出充足的迁移时间。具体时长会根据所需的迁移工作量逐案决定。

## 预发布版本

始终可以通过安装 `@next` 版本的 `@dcl/sdk` 包到场景中，来获取脚本框架的最新新增内容。

此分支中的功能可能不稳定或未有文档说明，因为它们并未作为官方受支持的 SDK 版本的一部分发布。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/api-can-kao/version-support-agreement.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.