Sway 破坏性版本发布清单实验性功能晋级、forc migrate 迁移注册与文档收尾全流程【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway本篇技术指南以 Sway 仓库内docs/breaking-release-checklist.md这份破坏性Breaking版本发布检查清单为骨架系统讲解 Sway 编译器如何通过实验性功能Experimental Featuresforc migrate迁移工具来受控引入破坏性变更的完整生命周期。你将掌握实验性功能开关的定义与优先级、forc migrate三个子命令与迁移步骤的注册/注销机制、将实验性功能转正为稳定功能时需要清理的编译器条件代码、Sway 代码库、E2E 测试与 CI 配置以及破坏性版本发布前必须完成的文档同步工作——这份清单正是维护者每次发布破坏性版本时的免检手册。为什么需要这份清单Sway 的破坏性变更管理机制Sway 语言与编译器在演进过程中会以受控的方式引入可能破坏现有合约编译结果的新特性。为此仓库中实现了一套实验性功能Experimental Features机制其核心设计目标有三类见 实验性功能参考文档承载开发期不稳定的较大语言特性例如 References 引用特性以受控方式引入破坏性变更例如 Partial equivalence 部分等价比较在不兼容变更发生时保留旧编译器行为作为退路例如 New hashing 新哈希方案。这套机制保证了破坏性变更不是一夜间全量生效而是先以带开关的实验性功能形式提供给早期采用者待稳定后再在某个破坏性版本中转正。而docs/breaking-release-checklist.md正是这个转正并发布阶段的操作清单它把整个发布流程拆解为四大检查项确保实验性功能从带门控的试验品平滑过渡为默认开启的稳定行为同时不遗留任何测试、文档或迁移工具的半成品状态。实验性功能的定义与开关机制源码级所有实验性功能都在独立的 cratesway-features中集中注册其入口为 sway-features/src/lib.rs。该文件通过features!宏一次性生成Feature枚举、ExperimentalFeatures结构体及其解析逻辑当前仓库注册的实验性功能如下enabled表示是否默认开启Feature功能名默认值用途new_encodingtrue新的编码encoding v1方案替代即将退位的 encoding v0referencestrue引用References类型特性new_hashingtrue新哈希方案改变字符串、数组等类型的哈希结果str_array_no_paddingfalse字符串数组str[N]去除 8 字节对齐填充的新运行时布局dynamic_storagefalse动态存储特性在编译器内部每个功能对应的条件编译参数统一为experimental_feature_name如experimental_new_hashing由Feature::CFG常量批量生成见sway-features/src/lib.rs中stringify!([experimental_ $name:snake])的宏展开。当某功能被关闭时编译器会通过FeatureIsDisabled编译错误提示用户并附上该功能的追踪地址。实验性功能支持三种粒度的开关方式且存在严格的覆盖优先级该顺序直接写死在ExperimentalFeatures::new的文档注释与实现中Forc.toml中[project]下的experimental字段无特定顺序CLI 参数--no-experimental禁用CLI 参数--experimental启用环境变量FORC_NO_EXPERIMENTAL禁用环境变量FORC_EXPERIMENTAL启用。即环境变量覆盖 CLI 参数CLI 参数覆盖Forc.toml配置。Forc.toml中未列出的功能则使用其默认开关值。对应的命令行示例如下# Forc.toml: experimental { some_feature true, some_other_feature false } forc build --experimental some_feature --no-experimental some_other_feature forc build --experimental some_feature_1,some_feature_2 FORC_EXPERIMENTALsome_feature,other_feature forc build FORC_NO_EXPERIMENTALsome_feature,other_feature forc build这些开关还支持配合#[cfg(experimental_feature true/false)]属性进行条件编译让同一份代码在两个行为模式下共存详见 attributes 文档 与 experimental_features.md#[cfg(experimental_some_feature true)] fn conditionally_compiled() { log(仅在启用 some_feature 时编译); } #[cfg(experimental_some_feature false)] fn conditionally_compiled() { log(仅在禁用 some_feature 时编译); } #[cfg(experimental_some_feature true)] #[cfg(experimental_some_other_feature true)] fn conditionally_compiled() { log(仅当两个实验性功能都启用时编译); }正是这套cfg(experimental_*)门控让同一次破坏性变更可以在仓库内std标准库、E2E 测试、语言内测试等长期共存两套实现这也是清单中移除条件代码工作如此繁重的原因。检查项一确保最新补丁版本中的 forc migrate 已包含全部迁移步骤破坏性版本发布的前置条件是在破坏性版本之前的最后一个补丁patch版本中forc migrate工具必须已经包含本次破坏性变更所需的全部迁移步骤。这意味着迁移能力必须先于破坏性版本本身交付给用户让用户在升级前就能提前预览、规划乃至执行迁移。forc migrate 插件与三个子命令forc migrate是一个 forc 插件源码位于 forc-plugins/forc-migrateCLI 入口在 forc-plugins/forc-migrate/src/cli/mod.rs它提供三个子命令forc migrate show列出即将到来的破坏性变更功能及其迁移步骤。输出Breaking change features:清单并按执行方式统计 Migration steps (N manual, N semiautomatic, N automatic)随后逐条列出步骤每步用[M]Manual 手动、[S]Semiautomatic 半自动、[A]Automatic 自动标注见 show.rs。forc migrate check对迁移步骤做 dry-run预演只报告代码中需要处理的位置而不实际改动源码最后输出Migration effort迁移工作量汇总统计每步的发生次数Occurrences并按count × duration估算耗时若没有任何需要迁移的位置则提示 Project is compatible with the next breaking change version of Sway见 check.rs。forc migrate run真正执行迁移步骤并引导开发者走完整个迁移流程见 run.rs支持--path path指定项目、--offline离线模式、--locked锁定依赖等参数并且会一并迁移测试代码源码中include_tests true。如果项目无法编译工具会提示检查是否遗漏了--experimental feature_1,feature_2参数。forc migrate show # 查看即将到来的破坏性变更与迁移步骤 forc migrate check # 预演迁移报告需要处理的位置与工作量 forc migrate run # 引导执行迁移 forc migrate run --path my_project --offline迁移步骤的注册机制迁移步骤集中定义在 forc-plugins/forc-migrate/src/migrations/mod.rs。每个破坏性变更功能对应一个子模块如new_hashing、str_array_layout、partial_eq、references等其中定义若干MigrationStep。MigrationStep包含四个字段title步骤标题格式为对开发者建议的续句You should title手动步骤的标题以 Review 开头duration单个典型出现点的手动迁移耗时估计分钟只有全自动步骤允许为 0kind步骤种类见下help面向开发者的短帮助文本自动修改代码的步骤以 Migration will 开头。kind分为三种MigrationStepKind枚举Instruction(InstructionFn)纯指导型步骤只分析程序并返回需要开发者手动处理的位置Occurrences不改动源码归类为 ManualCodeModification(CodeModificationFn, manual_actions, continue)自动修改源码的步骤可能附带迁移后仍需开发者手动完成的动作列表manual_actions若无手动动作则为全自动Automatic否则为半自动SemiautomaticInteraction(InstructionFn, InteractionFn, manual_actions, continue)先给指导、再与开发者交互征询决定的步骤开发者可选择执行、跳过或推迟InteractionResponse中的ExecuteStep/StepNotNeeded/PostponeStep归类为 Semiautomatic。所有步骤集中注册在MIGRATION_STEPS常量中按功能分组见migrations/mod.rs中MIGRATION_STEPS定义当前注册了new_hashing与str_array_no_padding两个功能各自的 Review 步骤并经过assert_migration_steps_consistency做一致性校验每个功能只能出现一次、步骤标题必须唯一、仅全自动步骤可设零耗时。get_migration_steps_or_return!宏则在步骤为空时提示 There are currently no migration steps defined for the upcoming breaking change version of Sway 并提前返回——这正是未注册任何迁移步骤状态的标准输出也就是清单中第三步注销后的表现。作为实例new_hashing.rs 中的步骤REVIEW_EXISTING_USAGES_OF_STORAGE_MAP_SHA256_AND_KECCAK256是一个典型的 Instruction 步骤它提示开发者新哈希会改变str、str[N]、[T; N]、raw_slice、VecT、Bytes等类型的哈希值需要审查这些类型是否作为StorageMap的 key、是否出现在自定义存储类型中、是否被sha256/keccak256直接哈希str_array_layout.rs 则针对字符串数组运行时布局变更给出数据迁移建议用[u8; M]模拟旧填充读取存量数据。检查项二将实验性功能转正为稳定功能破坏性版本中实验性功能要被晋升为默认且不可关闭的标准行为这要求彻底移除围绕该功能的全部门控与条件分支。清单列出了五个子任务1. 移除编译器中的 feature flag 与全部条件代码从sway-features的features!宏列表中删除该功能的注册项并清理编译器sway-core等内部所有FeatureIsDisabled错误路径、is_enabled_for_cfg查询及围绕开关if/else分支的代码使新行为成为唯一路径。2. 移除 Sway 代码库中的 experimental cfg 属性在sway仓库内所有 Sway 代码std标准库 sway-lib-std、E2E 测试、语言内测试等中删除所有#[cfg(experimental_feature ...)]属性及其包裹的旧实现分支只保留新行为对应的代码让同一份源码不再需要按开关编译。3. 删除 E2E 测试中的 test. .toml 文件E2E 测试位于test/src/e2e_vm_tests每个测试用例目录下带有test.toml之类的配置。针对实验性功能测试通过test.feature.toml这类按功能命名的配置文件来指定在特定开关组合下运行例如指定--experimental dynamic_storage的专用测试组。转正后这些按功能拆分的测试配置不再有意义应整体删除让测试回归到默认编译路径下执行。4. 移除 ci.yml 中的实验性功能测试仓库 CI 工作流 .github/workflows/ci.yml 中维护着针对各实验性功能的专项测试任务例如对 sdk-harness 与语言内测试分别以不同开关组合构建# 关闭 new_hashing验证旧哈希行为仍可用 - run: cargo run --locked --release -p forc -- build --locked --path ./test/src/sdk-harness --no-experimental new_hashing --output-directory ./test/src/sdk-harness/out # 开启 str_array_no_padding / dynamic_storage验证新行为 - run: cargo run --locked --release -p forc -- build --locked --path ./test/src/sdk-harness --experimental str_array_no_padding --output-directory ./test/src/sdk-harness/out - run: ./test/src/in_language_tests/run_in_language_tests.sh --experimental dynamic_storage --filter storage功能转正后这些以--experimental/--no-experimental拆分 CI 矩阵的步骤应从ci.yml中移除只保留稳定默认配置下的测试。5. 关闭 GitHub 追踪问题tracking issues每个实验性功能在仓库中都有一个带tracking-issue标签的追踪问题记录特性的详细描述与引入的破坏性变更当前活跃与已集成的功能清单见 experimental_features.md 中的说明。功能转正后关闭对应的 tracking issue标志着该功能的实验期正式结束。检查项三在破坏性版本中注销迁移步骤但保留代码作为示例迁移步骤注册表MIGRATION_STEPS中关于该功能的步骤要注销unregister即不再作为活跃迁移步骤对外提供。但清单特别强调不要删除Do not delete这些迁移实现。其理由在migrations/mod.rs的注释中写得很明确Change those steps for every new breaking change version of Sway, by removing the previous steps and adding the ones relevant for the next breaking change version.保留旧迁移有两个目的其一它们可以作为未来类似破坏性变更的迁移步骤范例其二它们承担学习与测试用途——migrations/mod.rs中甚至专门保留了demo子模块内含用于学习与测试迁移工具的演示迁移The specialdemosubmodule contains demo migrations used for learning and testing the migration tool。注销后用户运行forc migrate时若没有活跃步骤将看到get_migration_steps_or_return!宏打印的提示信息而非报错。检查项四发布前的文档收尾破坏性版本发布前文档工作同样不可遗漏清单给出三个子项确保实验性功能本身已被完整记录该功能的最终行为、用法、与旧行为的差异必须在官方文档如 Sway Book中有完整章节读者无需依赖 tracking issue 就能理解新特性移除所有将功能描述为实验性的 Note文档中凡是标注该功能为 experimental、并附带将来可能变更警示语的旁注都应删除或改写为稳定行为描述更新所有相关文档包括 manifest 参考Forc.toml中experimental字段的说明、属性参考#[cfg]条件编译说明、实验性功能总览 以及示例代码等确保文档与转正后的编译器行为一致避免遗留开关已不存在的过时指引。清单背后的完整生命周期从实验性功能到稳定特性把上述检查项串联起来可以还原 Sway 破坏性变更的完整工作流开发期新特性以实验性功能形式注册于sway-features通过Forc.toml/ CLI / 环境变量三重开关控制配合#[cfg(experimental_*)]条件编译在仓库内共存新旧实现预发布期在破坏性版本的前一个补丁版本中为forc migrate注册好该功能的全部迁移步骤MIGRATION_STEPS让用户提前通过show/check/run评估与执行迁移发布期按清单执行——移除编译器与 Sway 代码中的全部门控、删除按功能的测试配置与 CI 任务、关闭 tracking issue、注销迁移步骤但保留实现作为示例、完成文档收尾随后发布破坏性版本沉淀期旧迁移代码与demo迁移一起作为后续破坏性变更的参考资料长期保留。结语docs/breaking-release-checklist.md虽是一份不足二十行的勾选清单却是 Sway 团队管理破坏性变更的核心操作规程。它背后对应着一套可执行的工程体系sway-features负责功能的注册与开关解析forc-migrate负责迁移步骤的注册、校验与执行.github/workflows/ci.yml负责实验性功能的矩阵化验证而文档体系则保证用户始终能看到与当前编译器一致的行为说明。对希望在 Sway 生态中平稳跨版本升级的开发者而言理解这条清单等同于理解破坏性版本发布前官方如何保证迁移工具、测试与文档三者就绪对编译器维护者而言它更是一份可以直接照着执行的发布 SOP。相关参考文件docs/breaking-release-checklist.md本文依据的原始清单sway-features/src/lib.rs实验性功能注册与开关解析docs/book/src/reference/experimental_features.md实验性功能使用文档forc-plugins/forc-migrate/src/migrations/mod.rs迁移步骤注册表与一致性校验forc-plugins/forc-migrate/src/cli/commands/check.rs 与 run.rscheck / run 实现.github/workflows/ci.yml实验性功能 CI 测试矩阵【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考