wandb 开源贡献完全指南从环境搭建、Conventional Commits 到自动化代码生成【免费下载链接】wandbThe AI developer platform. Use Weights Biases to train and fine-tune models, and manage models from experimentation to production.项目地址: https://gitcode.com/gh_mirrors/wa/wandb本篇指南以 wandb 仓库根目录下的 CONTRIBUTING.md 为主体系统讲解向 Weights BiasesAI 开发者平台用于模型训练、微调与从实验到生产的全流程管理贡献代码的完整流程从 Fork 仓库、遵循 Conventional Commits 提交规范到搭建 Python/Go/Rust 三语言开发环境、构建安装、代码生成Protocol Buffers、GraphQL、Telemetry以及测试与故障排查。读者读完可以完整掌握 wandb 的社区协作规范并具备实际提交一个可被合并的 Pull Request 的全部技能。一、Development Workflow一次贡献的完整生命周期1.1 从 Issue 出发在动手写代码之前请先在仓库的 Issues 页面检索确认你想实现的功能或修复的 Bug 是否已被提出若已有对应 Issue直接在其下补充讨论若没有新建一个 Issue帮助项目团队跟踪功能请求与 Bug 报告避免重复劳动。1.2 Fork 与 Clone如果你是首次贡献者需要先点击仓库右上角的 Fork 按钮创建个人副本并配置 SSH 认证然后克隆并关联 upstreamgit clone https://github.com/your-username/wandb.git cd wandb git remote add upstream https://github.com/wandb/wandb.git开发期间保持 fork 与主仓库同步git checkout main git pull upstream main创建语义清晰的分支建议命名格式为username/short-dash-seperated-feature-descriptiongit checkout -b username/short-dash-seperated-feature-description1.3 开发、提交与 Pull Request开发过程中按逻辑拆分提交例如git add changed-file.py tests/test-changed-file.py git commit -m feat(integrations): Add integration with the awesomepyml library提交前务必通读 docs 目录下的编码规范与风格指南coding_style.md、general_advice.md 等按后文所述进行 测试 与 Lint确保提交信息符合 Conventional CommitsCI 会强制校验不符合将阻止 PR 合并。代码就绪后推送分支并创建 PRgit push origin username/short-dash-seperated-feature-descriptionGitHub 会返回创建 PR 的 URL。请在 PR 中编写信息量充足的标题与详细描述关联相关 Issue在描述中写 Fixeslink-to-the-issue 即可自动关联。评审提出修改意见后继续在同一分支提交并推送PR 会自动跟踪更新无需重建git add tests/test-changed-file.py git commit -m test(sdk): Add a test case to address reviewer feedback git push origin username/short-dash-seperated-feature-descriptionPR 通过评审后即被合并进主分支。二、Conventional Commits 提交规范wandb 要求所有 PR 标题遵循 Conventional Commits 规范提交信息结构为type(scope): description⭐ TLDR类型为feat或fix的提交是面向用户的。凡是面向用户的说明请确保用户能清楚理解提交内容。2.1 Types允许的提交类型TypeNameDescriptionUser-facing?featFeature新增直接影响用户的功能YesfixFix修复既有问题YesrefactorCode Refactor既不修复 Bug 也不新增功能的代码改动NodocsDocumentation仅文档变更MaybestyleStyle不影响代码含义的改动如 lintMaybechoreChores不修改源码的改动如 CI 配置、构建脚本NorevertReverts回滚之前的提交MaybesecuritySecurity安全修复/功能Maybe2.2 Scopes影响范围ScopeNameDescriptionsdkSoftware Development Kit不落入其他 scope 的改动integrationsIntegrations与第三方集成相关的改动artifactsArtifacts与 Artifacts 相关的改动sweepsSweeps与 Sweeps 相关的改动launchLaunch与 Launch 相关的改动leetLEET与 WB LEET TUI 相关的改动当一次改动跨越多个 scope 时选择对用户最相关的那一个。2.3 Subjects描述怎么写使用简短、祈使句式的描述。面向用户的说明fix/feat必须让用户明白发生了什么变化。✅好例子feat(sdk): add support for RDKit Molecules—— 用户能清楚知道产品引入了什么新能力。fix(sdk): fix a hang caused by keyboard interrupt on Windows—— 明确指出了在 Windows 上按 Ctrl-C 导致 SDK 挂起的 Bug 修复。❌坏例子fix(launch): fix an issue where patch is None—— 未说明引用的到底是什么问题。feat(sdk): Adds new query to the internal api getting the state of the run—— 未说明该信息对用户的价值更合适的类型可能是chore或标题应说明如何转化为面向用户的功能。三、搭建开发环境WB SDK 由 Python、Go、Rust 三种语言实现PythonSDK 主体wandb/目录Gowandb-core后端进程core 目录负责用户进程与后端的通信、文件传输、Filestream 等Rustwandb-xpu二进制xpu 目录用于监控硬件加速器Nvidia、AMD、Apple Arm GPU 以及 Google TPU。3.1 设置 Python推荐使用uv管理 Python 版本与虚拟环境。安装 uv 后执行uv python install 3.13 uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate接着在环境中安装 nox其默认 venv 后端即为 uvuv pip install nox3.2 设置 Go安装 core/go.mod 中指定的 Go 版本当前仓库要求go 1.27.1可用包管理器安装例如 macOS 下brew install go3.3 设置 Rust构建wandb-xpu需要 Rust 工具链安装方式curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y . $HOME/.cargo/env3.4 构建/安装包推荐以可编辑模式安装wandbuv pip install --reinstall --refresh-package wandb -e .如果你修改了 Go 或 Rust 代码需要重新运行该命令以重建并重装包编译逻辑可见于 noxfile.py 中的install_wandb辅助函数它会在开发模式下注入覆盖率与竞态检测相关的构建环境变量。3.5 Linting the Code仓库使用 prek 管理 linters 及其他自动生成代码。安装并注册钩子uv tool install prek prek install只想运行某个特定钩子例如格式化代码时prek run ruff-format --all-files --hook-stage pre-push仓库内置了多语言 pre-commit 钩子脚本见 core/scripts/pre-commit-hooks覆盖go-generate、go-mod-tidy、go-unit-tests、go-wire、rust-unit-tests等 Go/Rust 侧的质量门禁。3.6 Auto-Generating Code构建 Protocol Buffers仓库使用 Protocol Buffers 实现用户进程与 wandb 后端进程之间的通信。.proto源文件位于 wandb/protoPython 侧Go 侧生成产物位于 core/pkg/service_go_proto。若修改了任何.proto文件需运行 proto nox 命令重新生成绑定nox -t proto从 noxfile.py 的实现可见proto标签聚合了三个生成任务proto-pythonPython 绑定可按需指定 protobuf 主版本如nox -s proto-python -- 5 7、proto-goGo 绑定执行 core/api/proto/generate-proto.sh、proto-rustRust 绑定先通过 core/api/proto/install-protoc.sh 安装指定版本 protoc再执行 xpu/tools/generate-proto.sh。另有proto-check-*系列 session 用于校验生成产物与源码一致通过nox -t proto-check触发。注意只有当你确实修改了协议缓冲区文件时才需要执行此步骤。添加一个新 Setting新增配置项需要同步修改 Python 与 Proto 两侧更新wandb/sdk/wandb_settings.py::Settings类wandb_settings.py公开设置应声明为类属性可带默认值与校验方法如console_chunk_max_bytes: int 0、show_colors: bool | None None等模式均配合field_validator使用仅供内部使用、可修改的设置应以x_前缀命名如x_files_dir、x_sync_dir_suffix只读计算型设置应定义为类方法同时使用computed_field与property装饰器例如_args、_jupyter、_colab、_noop等见 wandb_settings.py仅内部使用时再加_前缀。在wandb/proto/wandb_settings.proto中按既有模式添加新字段然后运行nox -t proto重新生成 stubs。添加 URLs仅内部使用所有展示给用户的 URL 都应加入 wandb/errors/links.py以确保 URL 不会失效可使用dub.co服务缩短 URL。弃用功能Deprecating Features自 1.0.0 版本起wandb 将采用 Semantic Versioning所有向后不兼容的变更包括放弃对旧版 Python 的支持都会提升主版本号。当前标记为废弃的功能将在下一个主版本1.0.0中移除。将功能标记为废弃需要三步在wandb/proto/wandb_telemetry.proto的Deprecatedmessage 中添加一个新的布尔字段deprecated_feature运行nox -t proto重建协议缓冲区文件在代码中调用wandb.sdk.lib.deprecation.warn_and_record_deprecationfrom wandb.proto.wandb_telemetry_pb2 import Deprecated from wandb.sdk.lib.deprecation import warn_and_record_deprecation warn_and_record_deprecation( featureDeprecated(deprecated_featureTrue), # field name from step 1 messageThis feature is deprecated and will be removed in a future release., )该函数的实现位于 wandb/sdk/lib/deprecation.py它会通过telemetry.context将废弃标记合并进当前 run 的遥测数据并调用wandb.termwarn向用户展示一次警告repeatFalse避免重复刷屏实现告警 遥测统计双轨追踪。3.7 修改 GraphQL Schema如果 Server 端发生了影响 GraphQL API 的 schema 变更对于wandb-coreGo遵循 core/api/graphql/schemas/README.md 的说明对于wandbPython更新 core/api/graphql/schemas/commit.hash.txt 中的 commit hash当前指向cf541783f7cc389c59f1578e785ccebdd4a507d6重新运行nox -s gql-codegen。gql-codegensession 在 noxfile.py 中定义其核心是执行 tools/graphql_codegen/generate-graphql.shGraphQL 查询/变更定义.graphql文件与生成配置位于 core/api/graphqlPython 侧生成产物在wandb/apis/_generated与wandb/automations/_generated。四、Testing测试与本地验证4.1 使用 pytest仓库使用 pytest 框架测试位于 tests 目录单元测试在tests/unit_tests系统测试在tests/system_tests。所有测试依赖都应写入 requirements/requirements_dev.txt不同 Python 版本与平台还有对应的分平台文件如requirements_dev.3.13.linux.txt安装后即可运行uv pip install -r requirements/requirements_dev.txt然后用标准 pytest 命令运行测试pytest -s -vv tests/path-to-tests/test_file.py从 noxfile.py 的run_pytest可以看到仓库在 CI 中对 pytest 的加固配置默认--durations20打印最慢的 20 个测试、--timeout60单测超时、-nauto配合--maxprocesses10限制并行 worker 数量避免 tensorflow/pytorch 重导入导致内存打满、--splits/--group支持 CircleCI 分片并行并同时收集 Python 覆盖率与 Go 覆盖率。4.2 本地运行 system_tests仅内部[!NOTE] 出于安全限制外部贡献者无法运行系统测试。若你是内部工程师先启动本地测试服务器python tools/local_wandb_server.py start随后即可对system_tests运行 pytest结束后关闭服务器python tools/local_wandb_server.py stop4.3 归档 server 镜像仅内部system-tests-min-server-versionCI 任务会针对最旧受支持的 WB server 版本测试 SDK。已发布 server 版本的local-testcontainer镜像被归档在us-central1-docker.pkg.dev/wandb-client-cicd/images/local-testcontainer因为源 registrywandb-production只保留近期提交的镜像。归档为手动维护。当你需要尚未归档的版本时go install github.com/google/go-containerregistry/cmd/gcranelatest GITHUB_ACCESS_TOKEN$(gh auth token) nox -s local-testcontainer-registry上述命令会归档最新wandb/coreserver 发行版对应的镜像若已归档则为 no-op。若要归档特定版本传入其 tagGITHUB_ACCESS_TOKEN$(gh auth token) nox -s local-testcontainer-registry -- server/v0.81.3该逻辑实现在 noxfile.py 的local-testcontainer-registrysession 中通过 GitHub API 查询指定 tag 的提交 hash再用gcrane cp将镜像从wandb-production/images/local-testcontainer复制到归档 registry。你需要一个已通过gcloud认证、且既能读wandb-production/images/local-testcontainer又能写wandb-client-cicd/images/local-testcontainer的账号。五、Troubleshooting常见问题排查golangci-lint 版本不匹配典型报错示例Error: cant load config: the Go language version (go1.25) used to build golangci-lint is lower than the targeted Go version (1.26.2) The command is terminated due to an error: cant load config: the Go language version (go1.25) used to build golangci-lint is lower than the targeted Go version (1.26.2)原因是用旧版 Go 编译的golangci-lint无法解析要求更高 Go 语言版本的目标配置本仓库 core/go.mod 要求go 1.27.1。解决办法是清除 prek 缓存并重建prek cache clean该命令会重新构建golangci-lint通常即可解决版本不匹配问题。六、结语一次高质量的 wandb 贡献 Checklist结合全文提交一次 PR 前的自查清单如下Issue确认已有对应 Issue 或已新建分支username/feature-description语义化命名并保持与 upstream main 同步提交信息符合 Conventional Commitsfeat/fix面向用户可读环境Pythonuv nox、Gocore/go.mod 指定版本、Rust 工具链就绪构建uv pip install --reinstall --refresh-package wandb -e .可编辑安装改过 Go/Rust 后重新构建代码生成改过.proto跑nox -t proto改过 GraphQL 跑nox -s gql-codegen并更新 commit.hash.txt新增设置同步更新 wandb_settings.py 与wandb_settings.proto弃用按telemetry proto 字段 →nox -t proto→warn_and_record_deprecation三步走质量prek install安装钩子prek run ruff-format等钩子通过pytest单测通过PR信息丰富的标题与描述关联 Issue评审意见在同一分支继续提交推送。【免费下载链接】wandbThe AI developer platform. Use Weights Biases to train and fine-tune models, and manage models from experimentation to production.项目地址: https://gitcode.com/gh_mirrors/wa/wandb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
