ci-debian-versions.rst (7535B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Florian Dold 17 18 .. _ci-debian-package-versions: 19 20 CI Debian Package Versions 21 ========================== 22 23 The Debian publishers on ``buildbot.gnunet.org`` derive their package 24 versions from the highest eligible SemVer tag in the repository. The build 25 still uses the commit scheduled by Buildbot; selecting a version tag does 26 not change the source checkout. 27 28 This policy covers ``gnunet``, ``exchange``, ``merchant``, ``donau``, 29 ``challenger``, ``anastasis``, ``sync``, ``libeufin``, ``taler-rust``, 30 ``depolymerization``, ``taler-mailbox``, ``taldir``, and 31 ``taler-typescript-core``. All Debian packages produced by a repository use 32 its shared version helper. 33 34 Tag selection 35 ------------- 36 37 Eligible tags have the form ``vX.Y.Z`` or ``vX.Y.Z-dev.K``. Each numeric 38 component is a nonnegative integer without leading zeroes, except for zero 39 itself. Both annotated and lightweight tags are accepted. Optional SemVer 40 build metadata, such as ``+build.001``, is accepted but ignored in version 41 comparisons and omitted from the generated versions. 42 43 Selection compares the numeric components according to SemVer precedence. 44 For example, ``v1.2.3-dev.10`` sorts after ``v1.2.3-dev.9``, and 45 ``v1.2.3`` sorts after both. The highest eligible tag is selected across the 46 whole repository, including tags whose commits are not ancestors of HEAD. 47 Tag dates and proximity to HEAD do not determine the result. 48 49 When several tags have equal precedence, prefer the tag without build 50 metadata. If there is still a tie, choose the lexicographically first tag 51 name. Unsupported tags are reported and excluded. These include historical 52 forms such as ``v0.9.4a``, Debian-specific tags, and prereleases other than 53 ``-dev.K``. The generated snapshot forms below are reserved for CI output 54 and are not eligible release tags. Version generation fails if no eligible 55 tag exists. 56 57 Snapshot versions and ordering 58 ------------------------------ 59 60 Let ``N`` be the result of ``git rev-list --count TAG..HEAD``, where ``TAG`` 61 is the selected tag. A build is an exact tagged release only when 62 ``git rev-parse HEAD`` equals ``git rev-parse 'TAG^{commit}'``. A count of 63 zero alone does not establish an exact release: HEAD can be an ancestor of 64 the tagged commit. Such a build still receives a snapshot suffix with 65 ``N = 0``. 66 67 .. list-table:: Version mapping 68 :header-rows: 1 69 :widths: 30 35 35 70 71 * - Selected tag and checkout 72 - SemVer 73 - Debian version 74 * - ``vX.Y.Z``, exact commit 75 - ``X.Y.Z`` 76 - ``X.Y.Z`` 77 * - ``vX.Y.Z``, different commit 78 - ``X.Y.(Z+1)-0.N`` 79 - ``X.Y.(Z+1)~0.N`` 80 * - ``vX.Y.Z-dev.K``, exact commit 81 - ``X.Y.Z-dev.K`` 82 - ``X.Y.Z~devK`` 83 * - ``vX.Y.Z-dev.K``, different commit 84 - ``X.Y.Z-dev.K.N`` 85 - ``X.Y.Z~devK.N`` 86 87 ``Z+1`` means incrementing the patch component. For example, twelve commits 88 beyond ``v1.6.43`` produce SemVer ``1.6.44-0.12`` and Debian version 89 ``1.6.44~0.12``. Twelve commits beyond ``v1.6.44-dev.9`` produce 90 ``1.6.44-dev.9.12`` and ``1.6.44~dev9.12``. 91 92 A snapshot sorts after its selected tag in both systems. A stable-tag 93 snapshot sorts before the next patch's ``dev.0`` release; a development-tag 94 snapshot sorts before the next development tag, with ``K`` incremented 95 by one. For example, these sequences have matching order:: 96 97 1.6.43 < 1.6.44-0.12 < 1.6.44-dev.0 98 1.6.43 < 1.6.44~0.12 < 1.6.44~dev0 99 100 1.6.44-dev.9 < 1.6.44-dev.9.12 < 1.6.44-dev.10 < 1.6.44 101 1.6.44~dev9 < 1.6.44~dev9.12 < 1.6.44~dev10 < 1.6.44 102 103 The mapping also preserves equality. Neither a commit hash nor build 104 metadata is added to the Debian version to break a SemVer tie. Different 105 commits can therefore receive the same version, for example when their 106 counts relative to the selected tag are equal. Use the logged HEAD commit 107 and the artifact path containing the CI commit reference to identify a 108 particular build. 109 110 Buildbot checkout and packaging requirements 111 -------------------------------------------- 112 113 The container factories in ``taler-deployment.git/buildbot/master.cfg`` 114 retain full checkouts for these repositories. They use Git ``mode='full'``, 115 ``method='fresh'``, ``shallow=False``, and ``tags=True``. The fresh checkout 116 cleans build outputs while retaining Git history. The workspace preparation 117 step replaces a previous shallow checkout once, then keeps the full 118 checkout for subsequent builds. 119 120 Each repository provides ``contrib/ci/version.sh``, backed by 121 ``contrib/ci/debian-version.py``. Existing job-local ``version.sh`` paths 122 delegate to this entry point. Packaging containers must explicitly install 123 Python 3, including architecture-specific Containerfiles and templates used 124 to generate jobs. 125 126 The helper requires a full checkout and fetches all tags for the exact 127 scheduled commit with:: 128 129 git fetch --no-recurse-submodules --tags origin COMMIT 130 131 ``COMMIT`` is the full HEAD commit ID. Fetching by commit supports detached 132 HEADs and avoids guessing a branch name. Do not introduce a fetch depth 133 limit: incomplete history changes the commit count. A shallow checkout or a 134 failed fetch causes version generation to fail. 135 136 Standard output contains only the Debian version. Standard error records 137 the selected tag, HEAD commit, count, SemVer, and Debian version, as well as 138 excluded tags and errors. Packaging jobs must stop on errors and reject 139 empty output before changing the changelog or building packages. In a shell 140 script with ``set -e``, keep assignment separate from export:: 141 142 VERSION="$(./contrib/ci/version.sh)" 143 export VERSION 144 : "${VERSION:?version generation returned an empty version}" 145 146 Using ``export VERSION="$(...)"`` can hide the helper's failure status. 147 148 Maintaining and diagnosing the policy 149 ------------------------------------- 150 151 Keep ``contrib/ci/debian-version.py`` and ``contrib/ci/test_version.py`` 152 identical across the affected repositories. Run the conformance suite in a 153 Debian container with Git, Python 3, Bash, and ``dpkg`` installed:: 154 155 python3 contrib/ci/test_version.py 156 157 The suite exercises tag selection, detached checkouts, tags on other 158 branches, snapshot mapping, Debian ordering, compatibility entry points, 159 and packaging callers' error handling. The Debian ordering check is skipped 160 when ``dpkg`` is unavailable. Changes to checkout caching should also run 161 the Buildbot tests in ``taler-deployment.git/buildbot/test_container_steps.py``. 162 163 When a package version looks unexpected, first inspect the helper's 164 selected-tag and HEAD diagnostics. Check the highest eligible tag across 165 all branches, then compare the tagged commit to HEAD and inspect the 166 ``TAG..HEAD`` count. For a shallow-checkout failure, check the builder's 167 cache policy and workspace migration. For a fetch failure, check access to 168 ``origin`` and the scheduled commit. Fix the checkout or tag problem before 169 retrying the package build.