Dangerzone 发布前准备完全指南pre-release 任务清单、版本号多点同步与 Linux 平台维护【免费下载链接】dangerzoneTake potentially dangerous PDFs, office documents, or images and convert them to safe PDFs项目地址: https://gitcode.com/GitHub_Trending/da/dangerzoneDangerzone 的发布流程分为六个阶段其中“Pre-release发布前准备”是全部工作的起点它要求发布管理者在构建任何发行物之前就完成问题跟踪创建、依赖锁文件刷新、多处版本号同步、Linux 平台清单维护、Debian changelog 更新、发布说明草稿和 rc1 标签等一系列前置任务。本文基于仓库中 发布前准备文档 完整展开这份任务清单并结合 generate-release-tasks.py、dev_scripts/qa.py 等源码说明每个步骤背后的实际机制帮助你理解“为什么必须改这些文件、改哪里、如何验证”。一、Pre-release 在整体发布流程中的位置Dangerzone 需要同时面向 Debian、Ubuntu、Fedora、Qubes OS、macOS、Windows 多个发行渠道出包因此其发布被拆分为六个阶段见 发布流程总览Pre-release发布前准备即本文主题Prepare build environments准备构建环境Sign and release container image签名并发布容器镜像Build release artifacts构建发行物QAReleasePre-release 阶段的特殊性在于它完全可以在开发者自己的笔记本上执行不依赖任何构建环境。原文档明确说明“Here is a list of tasks that should be done before issuing the release. They can run from the developers laptop and are not tied to any build environment.”这一点很关键——所有任务都是修改仓库内容版本号、文档、changelog、依赖锁而非触发 CI。1.1 用一个 issue 跟踪整体进度任务清单的第一步是创建一个名为QA and Release for versionVERSION的 GitHub issue用来跟踪整个发布周期的进度。issue 的正文内容可以自动生成poetry run ./dev_scripts/generate-release-tasks.py从源码结构看generate-release-tasks.py 的实现很精巧。它维护了一个文档列表RELEASE_DOCS_DIR pathlib.Path(docs) / developer / release DOCS [ pre-release.md, prepare-build-envs.md, build.md, qa.md, release.md, ]然后对每份文档执行extract_checkboxes()两轮扫描第一轮收集所有以#开头的标题行和所有- [ ]复选框行第二轮按 Markdown 标题层级裁剪只保留“当前标题层级及更浅层级”的内容这样生成的 issue 正文就是各阶段文档的目录级概览而不是每个子节都铺开的细节。由于它是按git rev-parse --show-toplevel定位仓库根目录后直接读取这五个 Markdown 文件的这意味着 release 文档本身就是 issue 内容的单一事实来源——后续修改文档中的复选框issue 模板会自动跟随变化。注意脚本中列出的prepare-build-envs.md与build.md对应当前仓库docs/developer/release/目录下的同名文件说明该目录是整份发布文档集的组织中心。二、依赖锁文件刷新两条并行的锁链Dangerzone 有两条互相独立的依赖链发布前都要刷新命令管理对象锁文件poetry lock --regeneratePython 依赖由 pyproject.toml 声明poetry.lockpoetry run mazette lock构建/发布所需的二进制资产asset 依赖mazette.lock前一条是标准的 Poetry 流程重新解析依赖并生成新的poetry.lock确保新发布携带当时最新兼容版本的 Python 包。后一条由 mazette仓库根目录下的mazette.lock即其产物管理。从 dev_scripts/env.py 与 dev_scripts/qa.py 的用法看poetry run mazette install是开发者本地下载运行所需资源二进制、字体等 assets的标准入口而poetry run mazette lock则在发布时刷新这些资产的固定引用——这与 dev_scripts/qa.py 中 QA 清单反复出现的 “Download the necessary assets usingpoetry run mazette install” 形成上下游呼应QA 环境安装的是 lock 文件里固定的资产版本因此发布前刷新 lock 能提前暴露资产引用问题。此外清单中还有一项外部工具检查查看 WiXWindows 安装包工具是否有新 release如有需要则升级。原文档同时引用了一个 issue 作为历史背景说明 WiX 版本曾与 Windows 构建产物兼容性相关——这一步属于“工具链升级”性质是否执行取决于当前 WiX 版本的稳定性。三、版本号的多点同步四个必须一致的位置这是 pre-release 中最容易出错的部分。仓库中版本号分散在四处必须全部更新到同一个值当前仓库快照中的实际值为0.11.0可作为参照格式位置说明当前仓库中的实际值pyproject.tomlPoetry 项目元数据第 3 行的version 0.11.0version 0.11.0share/version.txt单行纯文本版本文件运行时/构建脚本读取0.11.0install/linux/dangerzone.specRPM spec 文件第 37 行Version: 0.11.0debian/changelog需要新增一条changelog 条目而非改旧条目首条为dangerzone (0.11.0) unstable; urgencylow关于share/version.txt的读取方源码中有直接证据dev_scripts/env.py 中的dz_version()函数就是从该文件读取版本号def dz_version(): Get the current Dangerzone version. with open(git_root() / share/version.txt) as f: return f.read().strip()该函数随后被用于拼装本地包的匹配模式如{pkg_name}-{version}-*.fc{...}.rpm也就是说share/version.txt一旦与pyproject.toml不一致开发环境的包安装/测试脚本就会找不到对应产物。这解释了为什么原文档把这两个文件的更新列为并列的必做项。3.1 Debian changelog 条目“Bump the Debian version”的正确做法是在 debian/changelog顶部追加一条新记录格式参照既有条目dangerzone (0.11.0) unstable; urgencylow * Released Dangerzone 0.11.0 -- Freedom of the Press Foundation infofreedom.press Tue, 9 Jun 2026 15:25:20 0300每条包含版本头dangerzone (X.Y.Z) unstable; urgencylow、变更摘要行* Released Dangerzone X.Y.Z以及维护者签名行维护者、邮箱、日期。新发布只需把版本号替换为本次版本并更新日期即可。3.2 可选容器镜像 API 版本v1 → v2清单中还有一项可选项“Bump image version fromv1tov2, if the API has changed.”这里的 “image version” 指的是容器镜像仓库路径中的大版本段而非应用版本号。当前仓库 share/image-name.txt 的内容是ghcr.io/freedomofpress/dangerzone/v1dev_scripts/qa.py 的 QA 场景中同样以ghcr.io/freedomofpress/dangerzone/v1作为镜像标识进行升级验证“Dangerzone successfully installs the container image”场景。可以推断v1表示镜像格式/API 的第一代只有当镜像对外 API 发生不兼容变化时才需要切到v2并让各处引用跟随。若无 API 变更此项直接跳过——这与“宁可发布无聊而稳定的版本”README 原话 “either boring uneventful releases or gung-ho brittle ones. Pick your poison (the first one)”的发布哲学一致。四、文档与发布材料更新版本号同步完成后还有四项文档/材料类任务更新 INSTALL.md 中的下载链接使其指向新版本。当前仓库中这些链接形如https://github.com/freedomofpress/dangerzone/releases/download/v0.11.0/Dangerzone-0.11.0-arm64.dmgmacOS Apple Silicon、.../Dangerzone-0.11.0-i686.dmgmacOS Intel、.../Dangerzone-0.11.0.msiWindows。注意原文档的提示具体下载链接要等发布完成、资产上传后才能回填因此这一步在 pre-release 阶段先定位到需要替换的位置发布阶段再落实。如有必要更新 README.md 中的应用截图界面发生重大变化时。更新 CHANGELOG.md列出自上一版本以来所有重大变更。该文件采用 Keep a Changelog 格式并遵循语义化版本顶部维护一个[Unreleased]段发布时把 Unreleased 内容固化为新版本段。创建 draft release 草稿。发布说明文本从 docs/templates 目录的模板复制而来当前仓库包含两个模板release-notes-regular.md常规发布release-notes-security.md安全发布常规模板的骨架是一句总述新特性/稳定性改进/安全修复、亮点列表重大成果、新平台支持、社区贡献致谢末尾附指向 CHANGELOG.md 对应版本锚点的链接模板中的RELEASE_TAG、RELEASE_ANCHOR占位符需替换为实际标签与锚点。将发布说明送编辑editorial审校——这是流程性任务确保对外措辞准确。五、Linux 平台清单维护新增与移除这是 pre-release 中最需要外部信息输入的环节。当前支持的 Linux 发行版是Debian、Ubuntu 和 FedoraQubes OS 在发布层面被视为 Fedora 的特例。每个发布周期都要回答两个问题是否有新版本加入了是否有现有版本 EOL停止支持了原文档建议用 endoflife.date 这类工具查询各发行版的生命周期状态。5.1 新增一个平台版本beta / RC / 正式版均可原文档给出了五步流程下面结合源码展开每一步“具体要改哪”步骤 1加入 CI 工作流让该版本进入自动化测试。文档列出需要查看的位置是.circleci/config.yml与.github/workflows/ci.yml以及 dev_scripts/env.py 和 dev_scripts/qa.py。需要说明的是在当前仓库快照中CI 主工作流是 .github/workflows/ci.yml.circleci/config.yml未包含在本快照中文档中的该条目反映的是历史/并行配置。真正的“平台注册表”有两处都必须动dev_scripts/env.py基础发行版由DISTROS [debian, fedora, ubuntu]定义容器运行时为podman/docker更关键的是各发行版 Dockerfile 中对具体版本号的分支判断例如 Ubuntu 22.04/jammy 需要额外注入apt-tools-prod.sources与 conmon 升级步骤源于 dev_scripts/apt-tools-prod.pref 等配套文件Ubuntu 24.04/26.04/25.10 等新版则需要DOCKERFILE_UBUNTU_REM_USER片段来移除 23.04 起镜像自带的ubuntu用户。新增版本时若存在此类版本特化行为需要在这里登记。dev_scripts/qa.py每个受测平台对应一个类DISTROVERSION两个类属性即平台 ID。当前快照中的平台注册表为class QADebianBookworm(QADebianBased): DISTRO debian; VERSION bookworm class QADebianTrixie(QADebianBased): DISTRO debian; VERSION trixie class QADebianForky(QADebianBased): DISTRO debian; VERSION forky class QAUbuntu2204(QADebianBased): DISTRO ubuntu; VERSION 22.04 class QAUbuntu2404(QADebianBased): DISTRO ubuntu; VERSION 24.04 class QAUbuntu2604(QADebianBased): DISTRO ubuntu; VERSION 26.04 class QAUbuntu2510(QADebianBased): DISTRO ubuntu; VERSION 25.10 class QAFedora44(QAFedora): VERSION 44 class QAFedora43(QAFedora): VERSION 43这些类通过__init_subclass__自动注册进QABase.platforms字典键为get_id()返回的{DISTRO}-{VERSION}如ubuntu-24.04。因此新增平台 仿照现有类新增一个子类即可qa.py platform的 CLI 参数 choices 会自动包含它。步骤 2用dev_scripts/qa.py本地测试该版本。原文档特别强调“Focus on the GUI part, since the basic functionality is already tested by our CI workflows”——CI 已覆盖基础功能本地测试聚焦 GUI。运行方式poetry run ./dev_scripts/qa.py {distro}-{version}例如poetry run ./dev_scripts/qa.py ubuntu-26.04。从 dev_scripts/qa.py 的QALinux.start()看脚本会依次自动执行构建开发环境镜像调用env.py ... build-dev、poetry run mazette install下载资产、make test跑测试套件、构建.deb/.rpm包、构建 QA 端用户环境env.py ... build最后交互式逐项询问 QA 场景是否通过。常用选项有--try-auto自动尝试可自动化的步骤、--skip-manual跳过手动步骤、--check-refs只校验文档引用一致性后退出。还有一个值得了解的机制qa.py内置了Reference类把脚本中的CONTENT_QA、CONTENT_BUILD_*等缓存文本与 docs/developer/release/qa.md、BUILD.md 中的对应章节做一致性比对不一致就打印 diff 并以非零码退出。换句话说文档与自动化脚本之间有一道强制同步检查修改文档里的操作步骤时必须同步更新qa.py中的缓存副本。步骤 3更新 INSTALL.md 并记一笔 CHANGELOG.md。新平台要进入安装文档的支持列表同时在 changelog 中留痕供用户知晓支持范围变化。步骤 4若该版本是新的 stable 发布按需更新RELEASE.md与BUILD.md。当前仓库快照中对应内容以 BUILD.md 形式存在构建/运行开发环境说明qa.py的 Reference 检查也直接引用了它。步骤 5以上改动提 PR走正常评审合并流程。5.2 移除一个 EOL 版本原文档给出两步从仓库中移除对该版本的一切提及。除检查新增平台涉及的那些文件CI 配置、dev_scripts/env.py、dev_scripts/qa.py、INSTALL.md外用grep全局搜索版本号/代号如22.04、bookworm逐一清理——包括env.py中版本特化的 Dockerfile 分支、qa.py中对应的平台子类。在 CHANGELOG.md 中添加移除说明让用户知道某发行版版本不再被测试/支持。六、打 rc1 标签发布前准备的收尾动作清单最后一项git tag -s vversion-rc1 # 例如 git tag -s v0.9.1-rc1对main分支的 tip 打一个带签名的-rc1候选标签。使用签名标签-s而非-a/-m保证候选版本可被 GPG 验证-rc1后缀表明这是第一个 release candidate后续构建阶段将基于该标签而非移动的 HEAD构建与签名各平台产物从而保证“发布说明里声明的代码”与“用户实际下载的产物”严格对应。七、任务清单速查表把 pre-release.md 的完整清单整理为可执行顺序#任务涉及文件/命令性质1创建 “QA and Release for version X” issuepoetry run ./dev_scripts/generate-release-tasks.py生成正文必做2新增 Linux 平台 / 移除 EOL 平台dev_scripts/env.py、dev_scripts/qa.py、INSTALL.md、CHANGELOG.md必做按需3刷新 Python 依赖锁poetry lock --regenerate→poetry.lock必做4刷新资产依赖锁poetry run mazette lock→mazette.lock必做5检查并升级 WiXWindows 打包工具链外部工具版本检查按需6更新 pyproject.toml 的version第 3 行必做7更新 share/version.txt单行文本必做8更新 install/linux/dangerzone.spec 的Version:第 37 行必做9可选容器镜像 API 从v1升到v2share/image-name.txt 等引用处仅 API 变更时10Debian 版本 bump新增 changelog 条目debian/changelog必做11更新 INSTALL.md 下载链接发布后回填macOS/Windows 下载 URL必做12视情况更新 README.md 截图截图资产按需13更新 CHANGELOG.md 重大变更列表[Unreleased]段固化必做14从 docs/templates 模板创建 draft release 说明release-notes-regular.md必做15发布说明送编辑审校流程动作必做16对maintip 打签名标签vversion-rc1git tag -s v0.9.1-rc1必做八、小结pre-release 的本质回顾整个阶段它的设计逻辑可以概括为三句话一切以仓库内文本为单一事实来源。issue 模板由 release 文档自动生成QA 脚本内嵌文档章节并强制一致性检查版本号在四个文件中多点同步——任何一处遗漏都会在后续构建/QA 阶段以“找不到包”“链接失效”“签名对不上”等形式爆发。平台支持面是显式管理的资产。新增/移除 Linux 版本必须同时改 CI、env.py、qa.py、文档四处并留 changelog 痕迹而不是随新版本“顺带支持”。候选标签锁定发布基线。vversion-rc1签名标签把“要发布的代码”从移动的main上摘出来使后续签名、构建、QA、正式 release 各阶段都站在同一基线上。完成上述清单后仓库就进入了下一阶段——准备构建环境并签名容器镜像发布工作从“改文档和版本号”转入“出产物和验证”。【免费下载链接】dangerzoneTake potentially dangerous PDFs, office documents, or images and convert them to safe PDFs项目地址: https://gitcode.com/GitHub_Trending/da/dangerzone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考