Distroless 贡献指南：从 Bazel 构建、测试到提交补丁的完整工作流

云原生【免费下载链接】distroless Language focused docker images, minus the operating system.项目地址https://gitcode.com/GitHub_Trending/di/distroless点击查看免费下载导读本文以 distroless 仓库的 CONTRIBUTING.md 为骨架完整还原该项目的贡献者工作流从签署 Contributor License Agreement、使用 Bazel 构建镜像、通过./knife test运行测试、借助oci_load将镜像加载进本地 Docker、到修改 Debian 包清单后执行./knife lock重新生成锁文件以及最终提交 Pull Request 的完整流程。读完本文你将掌握这个基于 Bazel rules_oci 构建的 distroless 镜像仓库的本地开发环境搭建、构建测试方法与代码规范能够独立提交一个合规的补丁。一、贡献前的法律前置Contributor License Agreements与 Google 系开源项目一致distroless 接受补丁patch前必须先跨过法律门槛签署 Contributor License AgreementCLA。具体按贡献者身份分两种个人 CLAIndividual CLA适用于以个人身份编写原创源代码、且确定自己拥有其知识产权的开发者签署地址为 Google 的 individual CLA 页面公司 CLACorporate CLA适用于受雇于某家公司、代表公司贡献代码的开发者需要由公司签署 corporate CLA。签署完成后维护者即可接受你的 Pull Request。这一步是所有后续开发动作的前提任何补丁合入前都要求 CLA 已就绪。二、构建项目bazel build的正确用法distroless 仓库是一个纯 Bazel 工程模块依赖在 MODULE.bazel 中声明包括rules_oci 2.2.7、rules_distroless 0.8.0、container_structure_test 1.19.1、rules_go 0.63.0、rules_rust 0.63.0、rules_python 1.5.3等。整个项目的构建入口有二全量构建bazel build //...这会构建仓库中所有可构建目标。由于镜像按「架构 × 发行版 × 用户模式 × 调试模式」做了矩阵化展开见下文全量构建耗时较长日常开发更推荐定向构建单个镜像。定向构建单个镜像以构建base镜像为例bazel build //base:static_root_amd64_debian17目标名由//base:static_root_amd64_debian17构成语义可拆解为static镜像类型root用户模式amd64架构debian17发行版。这里的命名规则可以从 base/BUILD 与 base/base.bzl 中验证base_image/base_image_index/base_nossl_image等规则通过列表推导式对BASE_DISTROS、BASE_ARCHITECTURES、USERS、DEBUG_MODE做笛卡尔积展开生成base{mode}_{user}_{arch}_{distro}形式的目标名。例如 common/variables.bzl 定义了USERS [root, nonroot]与DEBUG_MODE [, _debug]因此每个发行版/架构组合都会产出root、nonroot、debug即_debug root与debug-nonroot四类目标。当前仓库的发行版与架构矩阵定义在 base/config.bzlBASE_DISTROS [debian13] BASE_ARCHITECTURES { debian13: [amd64, arm64, arm, s390x, ppc64le, riscv64], }也就是说本文写作时该仓库基于 Debian 13trixie支持 amd64、arm64、arm、s390x、ppc64le、riscv64 六种架构。三、运行测试为什么必须用./knife test而不是bazel test //...CONTRIBUTING.md 特别强调了一个容易踩坑的点bazel test //...并不会运行全部测试因为大量测试目标被标记为manual而./knife test才是完整的测试入口。原因藏在仓库根目录的 knife 脚本中其cmd_test实现如下function cmd_test () { local arch$(uname -m) if [ ${arch} x86_64 ]; then archamd64 fi arch_specific_targets$(bazel query attr(\tags\, $arch, \//...\)) bazel test --test_timeout900 //... $arch_specific_targets }可以看到./knife test做了两件事检测本机架构x86_64映射为amd64其余直接沿用uname -m输出用bazel query attr(\tags\, \arch\, \//...\)查询出所有打了对应架构 tag 的目标与//...一起交给bazel test并设置--test_timeout900兜底超时。这与镜像的结构测试机制相吻合例如 base/test.sh 通过container_structure_test的ext_run.sh运行而 base/testdata/base.yaml 用fileExistenceTests检查/etc/passwd、/etc/ssl/certs/ca-certificates.crt、/usr/share/zoneinfo、/var/lib/dpkg/status.d/libc6等文件是否存在和fileContentTests断言/etc/passwd中仅含root、nobody、nonroot三个用户/etc/os-release的PRETTY_NAMEDistroless对镜像内容做精确校验。这类测试按架构标记因此只有用./knife test才能把「当前架构」的镜像测试全部拉起来。环境提示在 macOS 上运行knife需要先执行brew install coreutils gnu-sed脚本会自动把 GNU 工具链路径注入PATH见 knife 第 20-25 行。四、把镜像加载到本地 Dockeroci_load规则如果你改完代码想在本机 Docker 引擎里实际跑一下镜像需要给该镜像在对应 BUILD 文件中新增一条oci_load规则。CONTRIBUTING.md 给出了完整模板load(rules_oci//oci:defs.bzl, oci_load) oci_load( name local_build, image //base:static_root_amd64_debian17, repo_tags [], )关键点说明load语句从rules_oci版本 2.2.7见 MODULE.bazel引入oci_load规则image字段指向你要加载的镜像目标即上文bazel build使用的目标名repo_tags为空列表时镜像加载后不附加额外 tag可自行填写如[myimage:latest]的形式。然后运行bazel run //:local_buildbazel run会先构建目标再执行加载动作把 OCI 镜像导入本地 Docker daemon之后即可用docker run直接启动验证。这也是本地调试镜像改动例如增删依赖包最直接的闭环。五、增删 Debian 包manifest 与 lock 文件的联动机制distroless 镜像的底层包依赖由 Debian 仓库清单驱动。每当你修改了common/*.yaml下的 manifest包清单必须执行锁定步骤重新生成 lock 文件否则构建会因锁文件与清单不一致而失败。./knife lock这一机制的实现细节值得展开manifest 文件存放在 private/repos/deb/ 目录当前有trixie.yaml、trixie_java.yaml、trixie_adoptium.yaml、trixie_python.yaml四份清单。以 trixie.yaml 为例其结构包含sources指向snapshot.debian.org的 main/updates/security 三个 channel 及精确时间戳快照、archs六种架构与packagesbase-files、ca-certificates、libc6、libssl3t64、tzdata、zlib1g等每个 manifest 对应一份名字.lock.json锁文件。仓库通过 deb.MODULE.bazel 中的apt.install扩展把 manifest、lock 文件与package.BUILD.tmpl模板绑定起来resolve_transitive False再用version.from_lock扩展把锁定版本导出为versions仓库供构建引用./knife lock的底层实现knife 第 27-60 行会先按是否引用snapshot.debian.org把仓库分为 snapshot 与 non-snapshot 两类然后对每个仓库执行bazel run ${repo}//:lock失败时等待 20 秒重试最多 10 次。此外./knife还提供了与包版本管理相关的辅助命令./knife deb-versions [-a architecture] [-p package] [-c codename]从private/repos/deb/*.lock.json中按架构、包名或发行版代号过滤并打印各包的精确版本./knife update-snapshots查询 snapshot.debian.org 上最新的 Debian 快照逐仓库更新debian/时间戳与debian-security/时间戳引用交互终端下会请求确认./knife update-non-snapshots只对非快照仓库重新锁定并顺带刷新 Java 版本update_java_versions_debian13。六、代码风格buildifier 与 pylintBazel 文件buildifier仓库的 BUILD/WORKSPACE/bzl 文件统一用buildifier格式化CONTRIBUTING.md 推荐安装 3.2.0 版本并执行# Install buildifier version 3.2.0 go install github.com/bazelbuild/buildtools/buildifierlatest # This will automatically fix files. buildifier -modefix $(find . -name BUILD* -o -name WORKSPACE* -o -name *.bzl -type f)-modefix会直接自动修正格式问题。knife也内置了 lint 命令knife 第 147-160 行./knife lint以 fix 模式运行./knife lint --check则只检查不修改若本机未安装buildifier脚本会提示「No buildifier executable was found. Did you follow the ./CONTRIBUTING.md ?」并退出。Python 文件pylint仓库中的 Python 代码如 private/pkg 下的 SPDX 生成器debian_spdx.go/oci_image_spdx.go的伴生逻辑与工具脚本使用 pylint 检查# Install pylint sudo pip install pylint # Or sudo apt-get install pylint # Or on macos brew install pylint # Identify python style issues. find . -name *.py | xargs pylint --disableR,C--disableR,C表示关闭重构Refactor与约定Convention类告警只保留错误Error与警告Warning级别的检查避免风格噪音淹没真正的问题。七、补丁提交流程Patch Contribution WorkflowCONTRIBUTING.md 给出了标准化的六步提交流程提交 Issue先在对应仓库提交一个描述你拟改动内容的 issue等待响应仓库所有者会及时回复该 issue签署 CLA若改动方案被接受且尚未签署 CLA按第一部分完成签署Fork 并开发fork 目标仓库在本地完成代码修改与测试构建、测试、lint 均通过提交 Pull Request将改动以 PR 形式提交等待维护者 review 与合入。其中第 4 步建议完整走一遍本文第二至六节描述的流程bazel build //...或定向构建确认编译通过./knife test确认当前架构下全部结构测试通过buildifier/pylint确认代码风格合规若改动涉及 Debian 包清单别忘了./knife lock重新生成锁文件并随 PR 一并提交。八、给贡献者的额外提示基于仓库源码的验证要点结合仓库源码以下三点能显著提高 PR 一次通过率镜像目标命名是矩阵化的新增镜像或修改 base/config.bzl 中的BASE_PACKAGES/BASE_NOSSL_PACKAGESbase 镜像默认包含libc6、libssl3t64、libzstd1、zlib1gnossl 变体仅含libc6时先在bazel query或bazel build中核对生成的目标名避免引用不存在的目标结构测试与镜像内容强绑定base/testdata/base.yaml 等测试数据断言了/etc/passwd用户集合、/etc/group组集合、os-release 内容等细节任何改变文件系统内容的改动都可能击穿测试务必在本地跑./knife test锁文件是构建的硬依赖deb.MODULE.bazel 中apt.install把 lock 文件作为构建输入修改 private/repos/deb/ 下任何*.yaml后忘记./knife lockCI 与本地构建都会失败。遵循以上流程与规范你就可以顺畅地为 distroless 项目贡献高质量的补丁了。赞分享云原生【免费下载链接】distroless Language focused docker images, minus the operating system.项目地址https://gitcode.com/GitHub_Trending/di/distroless点击查看免费下载相关推荐Bitcoin Core 贡献者指南从提交补丁到 Peer Review 的完整工作流Bitcoin Core 贡献者指南从提交补丁到 Peer Review 的完整工作流 本文以 Bitcoin Core 仓库根目录的 CONTRIBUTIN区块链金融科技网络密码学Skia 贡献指南从报 Bug、写测试到提交补丁的完整开发流程Skia 贡献指南从报 Bug、写测试到提交补丁的完整开发流程 Skia 是一个用于绘制文本Text、几何图形Geometries和图像Images图形学jQuery Core 贡献者实战指南从 Bug 报告到补丁提交的完整工作流jQuery Core 贡献者实战指南从 Bug 报告到补丁提交的完整工作流 jQuery 是一个被数以百万计站点依赖的开源 JavaScript 库本文以前端UI组件上一篇PapaParse CSV解析器终极指南5分钟快速上手JavaScript数据处理神器下一篇Latent Box中10个必知的AI产品从ChatGPT到Sora一站式掌握创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考