ungoogled-chromium 贡献指南新功能标准、补丁规范与提交流程全解析【免费下载链接】ungoogled-chromiumGoogle Chromium, sans integration with Google项目地址: https://gitcode.com/gh_mirrors/un/ungoogled-chromium本文基于 ungoogled-chromium 仓库的 docs/contributing.md 编写结合仓库内的补丁结构patches/series、开发流程docs/developing.md与验证工具devutils/进行深度扩充。读完本文你将掌握哪些贡献符合项目方向、新功能必须满足的硬性标准、如何通过 Pull Request 提交变更以及补丁提交前需要跑通的完整验证链路。一、文档定位与项目背景ungoogled-chromium 的核心目标是Google Chromium, sans integration with Google即去掉 Chromium 对 Google 网络服务的依赖同时尽可能保留原版 Chromium 的使用体验。这一目标决定了项目的贡献标准并非所有好功能都会被接受只有符合项目核心目标的改动才值得提交。官方贡献准则集中在 docs/contributing.md 一份文档中包含三个板块How to help普通人如何参与项目不一定需要写代码Submitting changes如何通过 Pull Request 提交代码、文档或修复Criteria for new features新功能被接受的硬性标准。值得注意的是文档明确区分了两类不适合进入主仓库的贡献不符合项目标准的小改动建议提交到外部 contrib 仓库或 Wiki官方支持平台的开发者应同时阅读平台仓库标准与指南。这意味着主仓库是平台无关的公共代码配置、补丁、脚本而平台特有的构建配置放在各自的 platform repo 中——这正是贡献者需要理解的第一件事。二、How to help不写代码也能贡献的五种方式贡献文档开篇列出项目长期需要的帮助类型按难度从低到高跟随 Chromium 版本更新跟踪最新的稳定版 Chromium以及新版本中导致 ungoogled-chromium 构建失败或行为变化的问题。这是最持续、最核心的维护工作。处理help wanted标签的 issue通常是面向其他用户的疑问或请求其他开发者协助的问题。审查他人的 Pull Request代码审查是开源项目最稀缺的资源之一。实现功能请求即 Issue Tracker 中标为 enhancements 的功能请求无论大小。实现backlog标签的 issue这些是已关闭但被标记为积压的 issue如果实现它们需要新代码必须通读本文后续的提交变更一节。此外任何人在 Issue Tracker 中帮助有需要的用户都是被鼓励的。也就是说提问与解答本身就是有效贡献。三、Submitting changes提交变更的基本规则文档明确要求所有变更一律通过 Pull Request 提交。具体规则如下规则说明欢迎小改动包括 bug 修复、文档修正、微调tweaks无需事先讨论声明认领如果你的改动关联某个 issue请先让大家知道你在处理它避免重复劳动新功能先读标准提交新功能前必须通读下一节的新功能标准不确定就先问对改动是否会被接受存疑时建议先通过 issue 提问从仓库的实际组织看提交变更主要涉及三类文件补丁文件位于 patches/ 目录按core/与extra/分类对应功能分为去 Google 集成/隐私增强核心与控制与透明度附加配置文件如 flags.gn、pruning.list、domain_substitution.list、domain_regex.list、downloads.ini工具脚本位于 utils/ 与 devutils/负责下载源码、剪枝二进制、域名替换、验证补丁等。3.1 一个小型提交的典型场景假设你要修复一个 patch 在最新 Chromium 上无法干净应用的问题。你需要先获取源码树详见 docs/developing.md 的下载流程用quilt修复补丁运行验证脚本确认无误提交 Pull Request。这类维护型改动正是文档欢迎的 minor changes不需要事先开 issue。四、Criteria for new features新功能被接受的硬性标准这是本文档最具技术约束力的部分原文只列了两条但每一条都对应仓库内可验证的实现机制。标准 1不得损害默认 Chromium 体验除非服务于项目核心目标New features should not detract from the default Chromium experience, unless it falls under the projects main objectives (i.e. removing Google integration and enhancing privacy).结合 README.md 中声明的目标优先级去除对 Google 网络服务的依赖最高优先级尽可能保留默认 Chromium 体验增强隐私、控制与透明度的微调几乎全部默认关闭需手动启用。当目标冲突时优先级高的目标胜出。例如禁用 Safe Browsing依赖 Google 服务虽然牺牲了一部分开箱体验但属于目标 1 的范畴因此是合理的核心改动而修改 UI 布局让浏览器更美观这类纯体验改动如果没有隐私/去 Google 属性就不符合标准。较大的功能必须先通过 issue 提案而不是直接提交 PR。标准 2新功能必须默认关闭且以命令行开关 / chrome://flags 形式提供New features should live behind a setting that isoff by default.这是仓库中最容易验证的一条标准。打开 docs/flags.md 可以看到ungoogled-chromium 引入了数十个--开关与--enable-features特性开关几乎全部默认关闭且每个开关在chrome://flags页面都有对应条目可通过搜索ungoogled-chromium过滤。贡献文档特别指出设置通常通过命令行 flag 和chrome://flags条目添加具体步骤见 docs/developing.md 的对应章节除非收益显著否则不建议加到chrome://settings因为支撑偏好设置preferences的基础设施会带来额外维护成本。从源码看 flag 的添加方式docs/developing.md 给出了新 flag 的实现路径参考 Chromium 源码树中的docs/how_to_add_your_feature_flag.md步骤无需更新tools/metrics/histograms/enums.xml先在third_party/ungoogled/ungoogled_switches.cc中添加常量通过修改补丁resources/patches/ungoogled-chromium/add-third-party-ungoogled.patch实现——注意这是开发流程文档中的路径描述实际对应本仓库中实现开关常量的补丁再在该常量基础上完成上述标准步骤。仓库中可见的对应补丁包括add-flag-to-configure-extension-downloading.patchadd-flag-to-disable-local-history-expiration.patchadd-flags-for-existing-switches.patch为 Chromium 已有但缺少 flags 页条目的开关补条目add-ungoogled-flag-headers.patch为 flag 添加统一头信息每个新功能对应一个独立 patch 文件并登记到 patches/series 中这构成了新功能 默认关闭的 flag 对应 patch series 登记的完整链路。附注非核心补丁的生命周期In the event that the codebase changes significantly for a non-essential patch (i.e. a patch that does not contribute to the main objectives of ungoogled-chromium), it will be removed until someone updates it.当 Chromium 上游发生重大变更导致某个非必要补丁不服务于去 Google 化或隐私增强的补丁无法继续维护时它会被移除直到有人更新它。这与 docs/design.md 中补丁目录的划分完全对应patches/core/涉及后台请求、Google 专有代码或预编译二进制必须跟随 Chromium 所有变更保持更新patches/extra/涉及控制与透明度的功能不保证在 Chromium 升级后仍然存活。因此extra 类补丁可能被移除不是威胁而是仓库明确的设计契约。提交此类补丁前请确认你愿意承担长期的跟进维护。五、深入仓库贡献者必须掌握的补丁基础设施要提交合格的新功能或补丁修复理解以下仓库组件是必要的。5.1 patches/ 目录与 series 文件docs/design.md 规定patches/ 目录遵循GNU Quilt 默认格式所有补丁必须位于patches/内patches/series 定义补丁应用顺序条目是相对patches目录的路径#开头的行被忽略补丁路径后若跟空格加#其后文本被忽略。补丁自身必须满足的格式要求要求说明扩展名.patch文件名必须以.patch结尾unified 格式内容必须为统一 diff 格式-p1路径hunk 头中的所有路径从第一个斜杠后开始干净应用补丁必须无 fuzz 地干净应用a/b/前缀推荐使用 git 默认的 3 行上下文与a/、b/前缀UTF-8 编码与配置文件编码一致5.2 quilt 工作流贡献者修改补丁的标准姿势docs/developing.md 提供了完整的补丁更新流程这是每个 patch 贡献者的必修课# 1. 设置 quilt 环境变量bash source devutils/set_quilt_vars.sh # fish shell 用户source devutils/set_quilt_vars.fish # 2. 进入源码树 cd build/src # 3. 刷新所有补丁 quilt push -a --refreshdevutils/set_quilt_vars.sh 的关键设置包括QUILT_PATCHES指向仓库根目录的patches/通过alias quiltquilt --quiltrc -规避绝对路径导致 quilt 无法读取QUILT_*_ARGS的问题QUILT_REFRESH_ARGS-p ab --no-timestamps --no-index --sort --strip-trailing-whitespace保证刷新后的补丁风格一致。若某个补丁刷新失败错误中断标准修复流程为quilt push -f强制应用失败补丁用quilt edit .../quilt add ...或quilt remove ...增删文件必要时逐行编辑quilt refresh刷新补丁回到第 3 步继续quilt push -a --refresh直到全部通过。提示当需要删除大段代码时文档建议逐行删除而不是用语言特性把代码藏起来。这既降低 quilt refresh 重新计算行号时的误伤概率也让只看补丁就能读懂变更意图。全部补丁刷新成功后quilt pop -a弹出所有补丁回到仓库根目录运行devutils/validate_config.py处理所有警告运行devutils/validate_patches.py -l build/src出现错误则回到补丁修复环节。5.3 验证工具链提交前的最后一道关仓库提供了一套完整的自动化验证体系提交 PR 前应确保全部通过devutils/validate_config.py对配置文件做静态健全性检查所有补丁文件存在所有补丁都被 series 文件引用每个补丁只使用一次flags.gn中的 GN 标志已排序且不重复downloads.ini符合其 schema。devutils/validate_patches.py验证所有补丁能干净应用-l / --local针对本地源码树验证源码树必须未修改否则结果无效-r / --remote从 Google 远程下载所需的源码文件验证需要 Pythonrequests模块内部使用 devutils/third_party/unidiff 逐 hunk 模拟应用补丁精确比对上下文行与删除行。配套脚本还有 devutils/check_patch_files.py检查补丁可读性、series 重复与未使用补丁、devutils/check_gn_flags.py 与 devutils/check_downloads_ini.py。仓库还提供统一的质量门禁脚本Linux/macOSdevutils/run_devutils_tests.sh运行 devutils 单元测试如 devutils/tests/test_validate_patches.py、devutils/tests/test_check_patch_files.pydevutils/run_utils_tests.sh运行 utils 单元测试如 utils/tests/test_patches.py、utils/tests/test_domain_substitution.pydevutils/check_all_code.sh全量代码检查入口。5.4 版本升级贡献更新 lists 与处理 domain substitution如果贡献涉及 Chromium 版本升级docs/developing.md 给出了明确流程下载源码推荐 tarball 方式mkdir -p build/download_cache ./utils/downloads.py retrieve -i downloads.ini -c build/download_cache ./utils/downloads.py unpack -i downloads.ini -c build/download_cache build/src更新二进制剪枝与域名替换清单./devutils/update_lists.py -t build/srcdevutils/update_lists.py 会扫描源码树对二进制文件执行剪枝判定写入 pruning.list对含 Google 域名的文本文件执行域名替换判定写入 domain_substitution.list。更新补丁重要更新补丁前必须确保尚未应用域名替换。若在域名替换已应用的情况下修复构建失败需按以下顺序操作# 先还原域名替换 ./utils/domain_substitution.py revert -c CACHE_PATH_HERE build/src # 按补丁更新章节修复补丁 # 重新应用域名替换 ./utils/domain_substitution.py apply -r domain_regex.list -f domain_substitution.list -c CACHE_PATH_HERE build/src关于域名替换的细节docs/design.md 说明替换后的域名以qjz9zk结尾且domain_regex.list中的条目必须以#分隔搜索与替换表达式替换表达式必须以qjz9zkTLD 结尾且搜索/替换必须一一对应、互不冲突。5.5 合并之后平台仓库的跟进贡献文档的最后一步同样关键PR 合并后如果你维护着ungoogled-software组织下的平台仓库需要同步更新各平台仓库。若你正考虑为某个官方支持平台提供长期维护请阅读平台仓库标准与指南其中规定平台仓库不得修改或删除主仓库中现有的补丁、GN flags、域名替换或二进制剪枝只能新增必须包含 ungoogled-chromium 版本号的标记/版本方案编译期间不得联网不应依赖外部构建服务ungoogled-software 组织仓库与 Chromium 所用仓库除外。六、结语一次高质量贡献的完整清单综合本文内容向 ungoogled-chromium 提交一次合格贡献的检查清单如下定位贡献类型是维护型小改动bug 修复、文档、微调还是新功能新功能自检是否默认关闭是否通过 flag /chrome://flags暴露而非塞进chrome://settings是否损害默认 Chromium 体验是否服务于去 Google 化或隐私增强大功能先提案通过 issue 说明设计等待社区反馈。补丁规范.patch扩展名、unified 格式、-p1路径、干净应用、UTF-8 编码。流程验证quilt push -a --refresh刷新 →devutils/validate_config.py→devutils/validate_patches.py -l build/src全部通过。提交 PR若关联 issue提前声明认领不确定是否会被接受先用 issue 询问。遵循这套标准你的贡献既不会偏离项目去掉 Google 集成、增强隐私的主航道也能最大概率被顺利合并。【免费下载链接】ungoogled-chromiumGoogle Chromium, sans integration with Google项目地址: https://gitcode.com/gh_mirrors/un/ungoogled-chromium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考