跳到主要内容

版本号

这个文档讲述了 openRuyi 的 Version 和 Release 以及 Epoch 字段的策略。

Version 字段包含上游项目的版本，而 Release 字段指定下游的发布编号。

定义​

对于某些上游来说，每一次提交 (commit) 本身都被视为一个版本。一些上游从不发布版本，而是让用户在任何给定时间直接从代码仓库中获取内容。

  • 发布版本 (release version) 上游开发者决定正式对外发布的软件版本。发布行为可能非常简单，例如只是在 Git 仓库中添加一个字段 (tag)。这也包括某些上游制作的所谓“小版本更新” (point releases) 或“补丁级别” (patchlevels)，因为它们同样被赋予了版本号并被正式发布。

  • 快照 (snapshot) 从上游的源代码控制系统 (如 Git) 中获取的代码归档，它不与任何一个正式的“发布版本”相关联。

  • 预发布版本 (prerelease version) 在正式版发布之前，许多上游会先确定新版的版本号，然后制作该版本的 "alphas"、"betas"、"release candidates" (RC，候选发布版) 等。这些版本虽然带有新版本号，但明确表示它们尚非最终版。我们称这些为预发布版本。在上游准备发布期间制作的任何快照 (snapshots) 也被视为预发布版本。

Version 字段​

Version 字段用来定义软件包的版本。以下是一张速查表:

情形应当采取的措施举例
版本号只带有半角句号 (.)可直接使用上游的版本号zstd: 1.5.7
1.5.7 → 1.5.7
版本号带有发布阶段标记 (alpha、beta、rc)将字母转为小写，并在字母前加波浪号 (~)libffi: v3.5.0-rc1
Version: 3.5.0~rc1
版本号本身带有短横线 (-)将短横线替换为小数点 (.)ImageMagick: 7.1.1-44
7.1.1-44 → 7.1.1.44
版本号本身带有下划线 (_)将下划线替换为小数点 (.)postgres: 17_6
17_6 → 17.6
版本号为格式化后带有半角句号的日期可直接使用上游的版本号u-boot: 2025.07
2025.07 → 2025.07
版本号为基于版本控制系统的提交哈希值由数字 0 作为开头，而后接上 +、版本控制器名称、打包日期 (YYYYMMDD) ，及哈希值的前 7 位gn: ee5b7e32b961a9da1933e9f46a018ba6cac8ef60
Version: 0+git20250808.ee5b7e3

大多数上游的版本控制方案都很简单: 它们由一个或多个版本组件组成，由点分隔。每个组件都是一个整数，可能带有前导零。组件也可以包含一个或多个 ASCII 字母 (大写或小写) 。

通常来说任何一个组件的值都绝不能在其左侧没有任何组件值增加的情况下降低 (指降低到排序更低的值) 。

遇到这种类型的版本控制方案，可直接在 Version 字段中逐字使用上游项目的版本号。不要移除前导零。

版本控制方案复杂的情况​

如果你遇到了这些情况，那么上面的方法是不适用的:

  • 上游从未定义过正式版本号；只有快照 (snapshots) 可供打包。

  • 上游使用的版本方案无法被 RPM 的版本比较算法正确排序。

  • 您希望打包一个预发布版本 (prerelease version)。

  • 上游一直遵循某种命名方案，但他们突然改变了规则，导致新版本无法正确排序。

此时，我们需要修改上游版本号，使其适用于 Version 字段。

使用波浪号处理预发布版本​

波浪号 (~) 专门用于处理那些不加修饰就无法正确排序的预发布版本。波浪号用于版本组件之前，它会使该组件的排序早于 (低于) 任何不带波浪号的组件。

例如，上游发布序列为 0.4.0、0.4.1、0.5.0-rc1、0.5.0-rc2、0.5.0。 那两个 "release candidates" 在 Version 字段中应分别记为 0.5.0~rc1 和 0.5.0~rc2。

使用点号处理补丁修复版本​

点号 (.) 专门用于处理那些上游发布的错误修复或“补丁级别”版本。上游所用的分隔符 (例如 -) 或者下划线 (例如 _) 可能需要被替换为点 (.) 或直接移除。

例如，如果上游发布了 0.5.0-post1 作为修复版，这个“发布后版本”在 Version 字段中应记为 0.5.0.post1。请注意，0.5.0.post1 的排序低于 0.5.1 和 0.5.0.1。

从未发布过版本的快照​

当上游项目从未指定过任何版本号时，在这种情况下，Version 字段以数字 0 作为开头，之后，必须在后面添加一个加号 (+) ，并紧随一个快照信息字段。

打包者可以在这个快照信息字段附加最多 17 个字符的额外信息，用于指明版本控制系统 (VCS) 和提交标识符 (commit ID)。

快照信息字段应使用以下格式: <scm><date>.<revision>。

  • <scm> 是一个标识上游 VCS 的短字符串 (例如 "git", "svn", "hg") 或 "snap"。

  • <date> 是一个八位数字 YYYYMMDD 格式的日期 (代表当前软件包的打包日期) 。

  • <revision> 是一个简短的 git 提交哈希 (commit hash) 、subversion 修订号，或有助于识别该快照在 VCS 中精确位置的其他标识符。如果 VCS 不提供此类标识符 (例如 CVS) ，则应省略此部分。

注意

<revision> 不应使用完整的哈希值，以避免 Version 字段字符串过长；通常只截取前 7 到 10 个字符。

发布过版本但后续仅发布快照版本的情况​

当上游项目之前指定过版本号，但后续因为某些原因不发布新版本的情况下，Version 字段以上游最后的版本号作为开头。之后，必须在后面添加一个加号 (+)，并紧随一个快照信息字段。

此时的快照信息字段应使用以下格式: <scm><date>.<revision>。

  • <scm> 是一个标识上游 VCS 的短字符串 (例如 "git", "svn", "hg") 或 "snap"。

  • <date> 是一个八位数字 YYYYMMDD 格式的日期 (代表当前软件包的打包日期) 。

  • <revision> 是一个简短的 git 提交哈希 (commit hash) 、subversion 修订号，或有助于识别该快照在 VCS 中精确位置的其他标识符。如果 VCS 不提供此类标识符 (例如 CVS) ，则应省略此部分。

注意

<revision> 不应使用完整的哈希值，以避免 Version 字段字符串过长；通常只截取前 7 到 10 个字符。

上游破坏了版本方案​

当上游项目突然采用一种完全不同的版本方案，甚至可能会将版本号重置为一个更低的值。如果以上的方法都无法构造出一个能正确排序的新 Version，或者导致新版本会低于已有的旧包版本。那么此时只能增加 Epoch 字段。

Epoch 字段​

Epoch 字段通常用来解决版本号歧义的问题，它只应在为避免版本问题时才被引入或增加。Epoch 字段一旦被引入到一个软件包中，就绝不能被移除或减少。

Release 字段​

定义软件包的发布号。此变量默认值应使用一个从 1 开始的整数 (不是 0) ，并且在每次修订软件包 (即下游重新打包) 时递增。

当 Version 字段被更改时，应该将数字复位为 1。