https://openruyi.cn/assets/js/d653a158.ab26059e.js

1"use strict";(globalThis.webpackChunkopenruyi_website=globalThis.webpackChunkopenruyi_website||[]).push([[7020],{88218(e,s,n){n.r(s),n.d(s,{assets:()=>d,contentTitle:()=>a,default:()=>l,frontMatter:()=>t,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"packaging-guidelines/versioning","title":"Version Numbers","description":"This document describes the openRuyi policy for the Version, Release, and Epoch tags.","source":"@site/docs/packaging-guidelines/versioning.md","sourceDirName":"packaging-guidelines","slug":"/guide/packaging-guidelines/Versioning","permalink":"/docs/guide/packaging-guidelines/Versioning","draft":false,"unlisted":false,"editUrl":"https://github.com/openRuyi-Project/homepage/edit/main/docs/packaging-guidelines/versioning.md","tags":[],"version":"current","frontMatter":{"id":"versioning","title":"Version Numbers","description":"This document describes the openRuyi policy for the Version, Release, and Epoch tags.","slug":"/guide/packaging-guidelines/Versioning"},"sidebar":"docSidebar","previous":{"title":"Package Splitting","permalink":"/docs/guide/packaging-guidelines/SplitPackage"},"next":{"title":"Reviewing","permalink":"/docs/category/reviewing"}}');var r=n(74848),o=n(28453);const t={id:"versioning",title:"Version Numbers",description:"This document describes the openRuyi policy for the Version, Release, and Epoch tags.",slug:"/guide/packaging-guidelines/Versioning"},a="Version Numbers",d={},c=[{value:"Definitions",id:"definitions",level:2},{value:"The <code>Version</code> tag",id:"the-version-tag",level:2},{value:"Cases Where the Versioning Scheme Is More Complex",id:"cases-where-the-versioning-scheme-is-more-complex",level:3},{value:"Using Tilde for Prerelease Versions",id:"using-tilde-for-prerelease-versions",level:4},{value:"Using Dots for Post-Release Patch Versions",id:"using-dots-for-post-release-patch-versions",level:4},{value:"Snapshots from Projects That Have Never Made a Release",id:"snapshots-from-projects-that-have-never-made-a-release",level:4},{value:"Projects That Used to Release Versions but Later Only Provide Snapshots",id:"projects-that-used-to-release-versions-but-later-only-provide-snapshots",level:4},{value:"When Upstream Breaks the Versioning Scheme",id:"when-upstream-breaks-the-versioning-scheme",level:4},{value:"The <code>Epoch</code> tag",id:"the-epoch-tag",level:2},{value:"The <code>Release</code> tag",id:"the-release-tag",level:2}];function h(e){const s={admonition:"admonition",br:"br",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(s.header,{children:(0,r.jsx)(s.h1,{id:"version-numbers",children:"Version Numbers"})}),"\n",(0,r.jsxs)(s.p,{children:["This document describes the openRuyi policy for the ",(0,r.jsx)(s.code,{children:"Version"}),", ",(0,r.jsx)(s.code,{children:"Release"}),", and ",(0,r.jsx)(s.code,{children:"Epoch"})," tags."]}),"\n",(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"Version"})," tag contains the upstream project's version, while the ",(0,r.jsx)(s.code,{children:"Release"})," tag specifies the downstream release number."]}),"\n",(0,r.jsx)(s.h2,{id:"definitions",children:"Definitions"}),"\n",(0,r.jsx)(s.p,{children:"Some upstream projects effectively treat each commit as a version. Some upstreams never make formal releases and instead expect users to obtain the code directly from the source repository at any time."}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.strong,{children:"Release version"}),": A software version that upstream developers intentionally designate and publish as an official release. The release process may be very simple, such as merely adding a tag in a Git repository. The definition of a release version also includes so-called ",(0,r.jsx)(s.em,{children:"point releases"})," or ",(0,r.jsx)(s.em,{children:"patch-level releases"})," that some upstreams produce, provided developers assign them a ver

1sion number and officially publish them."]}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.strong,{children:"Snapshot"}),": A source archive that you take from upstream source control (such as Git) that developers do not associate with any formal release version."]}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.strong,{children:"Prerelease version"}),": Before a final release, many upstreams first decide on the new version number and then publish versions such as ",(0,r.jsx)(s.em,{children:"alpha"}),", ",(0,r.jsx)(s.em,{children:"beta"}),", or ",(0,r.jsx)(s.em,{children:"release candidate"})," (RC). Although these builds already carry the upcoming version number, they explicitly indicate that they are not yet final. We refer to these as prerelease versions. We also consider any snapshots that developers produce in the period leading up to an upstream release to be prerelease versions."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(s.h2,{id:"the-version-tag",children:["The ",(0,r.jsx)(s.code,{children:"Version"})," tag"]}),"\n",(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"Version"})," tag defines the package version. The following table provides a quick reference:"]}),"\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n",(0,r.jsxs)(s.table,{children:[(0,r.jsx)(s.thead,{children:(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.th,{children:(0,r.jsx)(s.strong,{children:"Case"})}),(0,r.jsx)(s.th,{children:(0,r.jsx)(s.strong,{children:"Normalization rule"})}),(0,r.jsx)(s.th,{children:(0,r.jsx)(s.strong,{children:"Example (upstream \u2192 Spec)"})})]})}),(0,r.jsxs)(s.tbody,{children:[(0,r.jsxs)(s.tr,{children:[(0,r.jsxs)(s.td,{children:["Contains only dots (",(0,r.jsx)(s.code,{children:"."}),")"]}),(0,r.jsx)(s.td,{children:"Retain the upstream version as-is"}),(0,r.jsxs)(s.td,{children:["zstd: 1.5.7",(0,r.jsx)(s.br,{}),(0,r.jsx)(s.code,{children:"1.5.7"})," \u2192 ",(0,r.jsx)(s.code,{children:"1.5.7"})]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsxs)(s.td,{children:["Includes pre-release markers ",(0,r.jsx)(s.code,{children:"alpha"}),"/",(0,r.jsx)(s.code,{children:"beta"}),"/",(0,r.jsx)(s.code,{children:"rc"})]}),(0,r.jsxs)(s.td,{children:["Convert to lowercase and prefix with ",(0,r.jsx)(s.code,{children:"~"})]}),(0,r.jsxs)(s.td,{children:["libffi: v3.5.0-rc1",(0,r.jsx)(s.br,{}),(0,r.jsx)(s.code,{children:"Version: 3.5.0~rc1"})]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsxs)(s.td,{children:["Contains hyphen (",(0,r.jsx)(s.code,{children:"-"}),")"]}),(0,r.jsxs)(s.td,{children:["Replace ",(0,r.jsx)(s.code,{children:"-"})," with ",(0,r.jsx)(s.code,{children:"."})]}),(0,r.jsxs)(s.td,{children:["ImageMagick: 7.1.1-44",(0,r.jsx)(s.br,{}),(0,r.jsx)(s.code,{children:"7.1.1-44"})," \u2192 ",(0,r.jsx)(s.code,{children:"7.1.1.44"})]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsxs)(s.td,{children:["Contains underscore (",(0,r.jsx)(s.code,{children:"_"}),")"]}),(0,r.jsxs)(s.td,{children:["Replace ",(0,r.jsx)(s.code,{children:"_"})," with ",(0,r.jsx)(s.code,{children:"."})]}),(0,r.jsxs)(s.td,{children:["postgres: 17_6",(0,r.jsx)(s.br,{}),(0,r.jsx)(s.code,{children:"17_6"})," \u2192 ",(0,r.jsx)(s.code,{children:"17.6"})]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:"Date-based version with dots"}),(0,r.jsx)(s.td,{children:"Retain the upstream version as-is"}),(0,r.jsxs)(s.td,{children:["u-boot: 2025.07",(0,r.jsx)(s.br,{}),(0,r.jsx)(s.code,{children:"2025.07"})," \u2192 ",(0,r.jsx)(s.code,{children:"2025.07"})]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:"VCS commit-hash-based version"}),(0,r.jsxs)(s.td,{children:["Format as ",(0,r.jsx)(s.code,{children:"0+<vcs><YYYYMMDD>.<hash7>"})]}),(0,r.jsxs)(s.td,{children:["gn: ee5b7e32b961a9da1933e9f46a018ba6cac8ef60",(0,r.jsx)(s.br,{}),(0,r.jsx)(s.code,{children:"Version: 0+git20250808.ee5b7e3"})]})]})]})]}),"\n",(0,r.jsx)(s.p,{children:"Most upstream versioning schemes are straightforward: they consist of one or more version components separated by dots. Each component is an integer, possibly with leading zeros. A component may al

1so include one or more ASCII letters (uppercase or lowercase)."}),"\n",(0,r.jsx)(s.p,{children:"In general, a component's value must never decrease unless a component to its left increases."}),"\n",(0,r.jsxs)(s.p,{children:["For versioning schemes of this kind, you may use the upstream version literally in the ",(0,r.jsx)(s.code,{children:"Version"})," tag. Do not strip leading zeros."]}),"\n",(0,r.jsx)(s.h3,{id:"cases-where-the-versioning-scheme-is-more-complex",children:"Cases Where the Versioning Scheme Is More Complex"}),"\n",(0,r.jsx)(s.p,{children:"The approach above does not apply in the following situations:"}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsx)(s.p,{children:"The upstream never defines formal version numbers and provides only snapshots for packaging."}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsx)(s.p,{children:"RPM's version comparison algorithm cannot correctly order the upstream versioning scheme."}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsx)(s.p,{children:"You need to package a prerelease version."}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsx)(s.p,{children:"The upstream had followed a consistent naming scheme, but then suddenly changed the rules in a way that breaks version ordering."}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(s.p,{children:["In such cases, you must adapt the upstream version so that you can use it correctly in the ",(0,r.jsx)(s.code,{children:"Version"})," tag."]}),"\n",(0,r.jsx)(s.h4,{id:"using-tilde-for-prerelease-versions",children:"Using Tilde for Prerelease Versions"}),"\n",(0,r.jsxs)(s.p,{children:["Packagers specifically use a tilde (",(0,r.jsx)(s.code,{children:"~"}),") for prerelease versions that would not sort correctly otherwise. When you place it before a version component, it causes that component to sort earlier than any equivalent component without a tilde."]}),"\n",(0,r.jsxs)(s.p,{children:["For example, suppose the upstream release sequence is ",(0,r.jsx)(s.code,{children:"0.4.0"}),", ",(0,r.jsx)(s.code,{children:"0.4.1"}),", ",(0,r.jsx)(s.code,{children:"0.5.0-rc1"}),", ",(0,r.jsx)(s.code,{children:"0.5.0-rc2"}),", ",(0,r.jsx)(s.code,{children:"0.5.0"}),". Then you should write the two release candidates in the ",(0,r.jsx)(s.code,{children:"Version"})," tag as ",(0,r.jsx)(s.code,{children:"0.5.0~rc1"})," and ",(0,r.jsx)(s.code,{children:"0.5.0~rc2"}),"."]}),"\n",(0,r.jsx)(s.h4,{id:"using-dots-for-post-release-patch-versions",children:"Using Dots for Post-Release Patch Versions"}),"\n",(0,r.jsxs)(s.p,{children:["Packagers use a dot (",(0,r.jsx)(s.code,{children:"."}),") for bug-fix or patch-level versions that the upstream publishes. You may need to replace the separator the upstream uses (for example ",(0,r.jsx)(s.code,{children:"-"}),") or an underscore (",(0,r.jsx)(s.code,{children:"_"}),") with a dot (",(0,r.jsx)(s.code,{children:"."}),"), or remove it entirely."]}),"\n",(0,r.jsxs)(s.p,{children:["For example, if upstream publishes ",(0,r.jsx)(s.code,{children:"0.5.0-post1"})," as a post-release fix, you should write it in the ",(0,r.jsx)(s.code,{children:"Version"})," tag as ",(0,r.jsx)(s.code,{children:"0.5.0.post1"}),". Note that ",(0,r.jsx)(s.code,{children:"0.5.0.post1"})," sorts lower than both ",(0,r.jsx)(s.code,{children:"0.5.1"})," and ",(0,r.jsx)(s.code,{children:"0.5.0.1"}),"."]}),"\n",(0,r.jsx)(s.h4,{id:"snapshots-from-projects-that-have-never-made-a-release",children:"Snapshots from Projects That Have Never Made a Release"}),"\n",(0,r.jsxs)(s.p,{children:["When an upstream project has never assigned a version number, the ",(0,r.jsx)(s.code,{children:"Version"})," tag must begin with the digit ",(0,r.jsx)(s.code,{children:"0"}),", followed by a plus sign (",(0,r.jsx)(s.code,{children:"+"}),"), and then a snapshot information tag."]}),"\n",(0,r.jsx)(s.p,{children:"Packagers may append up to 17 characters of additional information in this snapshot tag to indicate the version control system (VCS) and the commit identifier."}),"\n",(0,r.jsxs)(s.p,{children:["The snapshot information tag should use the following format: ",(0,r.jsx)(s.code,{children:"<scm><date>.<revision>"})]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"<scm>"}

1)," is a short string identifying the upstream VCS, such as ",(0,r.jsx)(s.code,{children:"git"}),", ",(0,r.jsx)(s.code,{children:"svn"}),", ",(0,r.jsx)(s.code,{children:"hg"}),", or ",(0,r.jsx)(s.code,{children:"snap"}),"."]}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"<date>"})," is an 8-digit date in ",(0,r.jsx)(s.code,{children:"YYYYMMDD"})," format that represents the packaging date of the current package."]}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"<revision>"})," is a short Git commit hash, a Subversion revision number, or another identifier that helps locate the exact snapshot in the VCS. If the VCS does not provide such an identifier (for example, CVS), you should omit this part."]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(s.admonition,{title:"Note",type:"info",children:(0,r.jsxs)(s.p,{children:["You should not use the full hash value for ",(0,r.jsx)(s.code,{children:"<revision>"})," to avoid making the ",(0,r.jsx)(s.code,{children:"Version"})," tag excessively long. In most cases, the first 7 to 10 characters are sufficient."]})}),"\n",(0,r.jsx)(s.h4,{id:"projects-that-used-to-release-versions-but-later-only-provide-snapshots",children:"Projects That Used to Release Versions but Later Only Provide Snapshots"}),"\n",(0,r.jsxs)(s.p,{children:["When an upstream project previously assigned version numbers but later stops making new releases for some reason, the ",(0,r.jsx)(s.code,{children:"Version"})," tag should begin with the last upstream version number, followed by a plus sign (",(0,r.jsx)(s.code,{children:"+"}),") and a snapshot information tag."]}),"\n",(0,r.jsxs)(s.p,{children:["In this case, the snapshot information tag should use the same format: ",(0,r.jsx)(s.code,{children:"<scm><date>.<revision>"})]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"<scm>"})," is a short string identifying the upstream VCS, such as ",(0,r.jsx)(s.code,{children:"git"}),", ",(0,r.jsx)(s.code,{children:"svn"}),", ",(0,r.jsx)(s.code,{children:"hg"}),", or ",(0,r.jsx)(s.code,{children:"snap"}),"."]}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"<date>"})," is an 8-digit date in ",(0,r.jsx)(s.code,{children:"YYYYMMDD"})," format that represents the packaging date of the current package."]}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"<revision>"})," is a short Git commit hash, a Subversion revision number, or another identifier that helps locate the exact snapshot in the VCS. If the VCS does not provide such an identifier (for example, CVS), you should omit this part."]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(s.admonition,{title:"Note",type:"info",children:(0,r.jsxs)(s.p,{children:["You should not use the full hash value for ",(0,r.jsx)(s.code,{children:"<revision>"})," to avoid making the ",(0,r.jsx)(s.code,{children:"Version"})," tag excessively long. In most cases, the first 7 to 10 characters are sufficient."]})}),"\n",(0,r.jsx)(s.h4,{id:"when-upstream-breaks-the-versioning-scheme",children:"When Upstream Breaks the Versioning Scheme"}),"\n",(0,r.jsxs)(s.p,{children:["An upstream project may suddenly adopt a completely different versioning scheme, or even reset the version number to a lower value. If none of the methods above can produce a new ",(0,r.jsx)(s.code,{children:"Version"})," value that sorts correctly, or if the new version would sort lower than an already existing package version, then your only solution is to increase the ",(0,r.jsx)(s.code,{children:"Epoch"})," tag."]}),"\n",(0,r.jsxs)(s.h2,{id:"the-epoch-tag",children:["The ",(0,r.jsx)(s.code,{children:"Epoch"})," tag"]}),"\n",(0,r.jsxs)(s.p,{children:["Packagers usually use the ",(0,r.jsx)(s.code,{children:"Epoch"})," tag to resolve version-ordering ambiguities. You should introduce or increment it only when necessary to avoid versioning problems."]}),"\n",(0,r.jsxs)(s.p,{children:["Once you introduce an ",(0,r.jsx)(s.code,{children:"Epoch"})," tag for a package, you must never remove it or decrease its value."]}),"\n",(0,r.jsxs)(s.h2,{id:"the-release-tag",children:["The ",(0,r.jsx)(s.code,{children:"Release"})," tag"]}),"\n",(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"Release"})," tag defines the package release number. Its default value should be an integer starting from ",(0,r.jsx)(s.code,{children:"1"})," (not ",(0,r.jsx)(s.code,{children:"0"}),"), and you must increment it each time you revise the package downstream, that is, each time the downstream distribution repackages the softw

1are."]}),"\n",(0,r.jsxs)(s.p,{children:["Whenever the ",(0,r.jsx)(s.code,{children:"Version"})," tag changes, you must reset the numeric part of ",(0,r.jsx)(s.code,{children:"Release"})," to ",(0,r.jsx)(s.code,{children:"1"}),"."]})]})}function l(e={}){const{wrapper:s}={...(0,o.R)(),...e.components};return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},28453(e,s,n){n.d(s,{R:()=>t,x:()=>a});var i=n(96540);const r={},o=i.createContext(r);function t(e){const s=i.useContext(o);return i.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function a(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:t(e.components),i.createElement(o.Provider,{value:s},e.children)}}}]);