完成第一次发布

本教程使用正常的交互式命令行。你会创建 Semifold 配置、记录一份变更集、检查受影响的软件包、修改文件，并准备一次软件包仓库发布。

开始之前

准备一座默认分支为 main、工作区没有未提交修改的 Git 仓库。示例假设仓库中至少有一个包含有效 Cargo.toml 的 Rust 软件包；其他内置软件生态使用相同的生命周期。

如果 smif --version 还不能运行，请先按照安装指南安装 Semifold。

1. 初始化仓库

在仓库根目录运行：

smif init

交互提示会依次询问：

1. 要发现哪些软件包生态；
2. 基础分支和发布分支名称；
3. 是否使用默认的变更日志分类；
4. 是否生成 GitHub Actions 工作流。

本教程选择 Rust，分支保留 main 和 release，接受默认分类，并生成工作流。

打开 .changes/config.toml。在 [packages] 下确认每个软件包的路径和解析器符合预期。配置表的 key 是稳定的软件包 ID（PackageId），它可能不同于清单文件中用于发布的名称。

如果仓库已经初始化，只是后来增加或删除了软件包，请使用 smif config sync，不要再次运行 init --force。

2. 完成一项用户可见的改动

修改一个公开 API，或者完成其他使用者能感知的行为变化。第一次练习尽量保持改动小而明确，便于判断版本影响。

现在记录发布意图：

smif commit

按照提示选择发生变化的软件包，选择 patch、minor 或 major，选择变更日志分类，输入 add-api 这样的简短变更集名称，再写一段给使用者阅读的摘要。

Semifold 会创建类似下面的文件：

---
my-package: "minor:feat"
---

开放新的公共 API。

minor 表示期望的版本提升；feat 选择变更日志分组，不会选择发布通道。

把变更集与代码改动放在同一个提交或拉取请求中，让审查者一起判断实现和版本影响。

3. 检查受影响的软件包

smif status

如果软件包或版本不正确，请在这里停止。修改变更集、软件包 ID 或依赖配置，然后重新运行 smif status。

4. 选择自动或手工发布路径

如果 smif init 已经生成 GitHub Actions 工作流，推荐从这里开始交给自动化处理：

1. 推送代码改动和 .changes/add-api.md，再把这次拉取请求合入 main；
2. 生成的工作流运行 smif ci，更新配置中的 release 分支，并创建或刷新对应的发布拉取请求；
3. 在发布拉取请求中检查自动生成的版本与变更日志，确认后把它合入 main；
4. 下一次工作流运行发现已经没有待处理的变更集，于是按照依赖关系发布准备好的软件包版本。

同一次发布不要再在本地额外运行 smif version 或 smif publish。只有仓库没有使用生成的工作流，或者正在一次性测试仓库中专门学习手工机制时，才继续执行下面的命令。

5. 手工预览并应用版本修改

先预览待修改文件和待运行命令：

smif version --dry-run

预演不会应用正常的版本副作用。配置命令只有明确设置 dry-run = true 时才会在预演中运行，因此这类命令必须能够安全重复执行。

确认预览符合预期后，应用修改：

smif version

Semifold 会修改软件包版本和符合条件的内部依赖要求，写入变更日志，运行配置的版本修改后工作，并消费已经应用的变更集。

审查 Git diff，再运行仓库原有的测试。把生成文件提交到 release 分支，或者让生成的 GitHub Actions 工作流维护发布拉取请求。

6. 手工发布

版本修改进入用于发布的分支后，为相关软件生态提供所需的软件包仓库凭据。

先预览发布执行：

smif publish --dry-run

这条命令会验证软件包顺序并执行只读的版本存在性检查，但不会发布软件包，也不会创建代码托管平台 Release。

确认预览正确后执行：

smif publish

软件包按照依赖关系发布。最终报告会分别列出成功、跳过、失败和尚未开始的软件包。在持续集成环境中，如果还要创建已经配置的 GitHub Release 与附件，可以加入 --github-release。

发生失败时

• 找不到软件包：使用 .changes/config.toml 中 [packages] 的 PackageId，不要猜测软件包仓库名称。
• 工作区不干净：先检查并提交无关文件。--allow-dirty 表示有意接受当前 diff 作为输入，不会替你清理仓库。
• 软件包仓库中已经存在目标版本：Semifold 会跳过对应发布命令。启用 GitHub Release 时仍可以补建缺失的 Release；已经存在的 Release 不会触发附件恢复。
• 部分发布失败：根据最终报告中的成功、失败和尚未开始状态，修复失败的凭据、版本检查或命令后重试。不要手工再次发布已经确认存在的版本。

理解工作流后再做自动化

交互提示是正常的学习和本地维护路径。持续集成与输入受限环境可以通过参数提供相同答案：

smif init --resolvers rust \
  --base-branch main \
  --release-branch release \
  --default-tags \
  --github-actions

smif commit --name add-api \
  --package my-package=minor \
  --tag feat \
  --summary "开放新的公共 API。"

这些参数只是自动化兼容接口，不代表另一套发布模型，也不是开始使用 Semifold 的前置知识。

至此，你已经走完基础生命周期：发现软件包、记录变更集、联动修改相关版本与变更日志，再按依赖关系发布。仓库需要更多策略时，继续阅读配置概览。