Contributing to wandb

We at Weights & Biases ❤️ open source and welcome contributions from the community! This guide discusses the development workflow of the wandb library.

Table of Contents

• Development workflow
  • Conventional Commits
    • Types
    • Scopes
    • Subjects
• Setting up your development environment
  • Setting up Python
  • Setting up Go
  • Setting up Rust
  • Building/installing the package
  • Linting the code
  • Auto-Generating Code
    • Building protocol buffers
    • Adding a new setting
    • Adding URLs (internal use only)
    • Deprecating features
      • Marking a feature as deprecated
  • Modifying GraphQL Schema
• Testing
  • Using pytest
  • Running system_tests locally (internal-only)
  • Archiving server images (internal-only)
• Troubleshooting
  • golangci-lint version mismatch

Development workflow

1. Browse the existing Issues on GitHub to see if the feature/bug you are willing to add/fix has already been requested/reported.

   • If not, please create a new issue. This will help the project keep track of feature requests and bug reports and make sure effort is not duplicated.

2. If you are a first-time contributor, please go to https://github.com/wandb/wandb and click the "Fork" button in the top-right corner of the page. This will create your personal copy of the repository that you will use for development.

   • Set up SSH authentication with GitHub.

   • Clone the forked project to your machine and add the upstream repository that will point to the main wandb project:

     git clone https://github.com/<your-username>/wandb.git
     cd wandb
     git remote add upstream https://github.com/wandb/wandb.git
     

3. Develop your contribution.

   • Make sure your fork is in sync with the main repository:

   git checkout main
   git pull upstream main
   

   • Create a git branch where you will develop your contribution. Use a sensible name for the branch, for example:

   git checkout -b <username>/<short-dash-seperated-feature-description>
   

   • Hack! As you make progress, commit your changes locally, e.g.:

   git add changed-file.py tests/test-changed-file.py
   git commit -m "feat(integrations): Add integration with the `awesomepyml` library"
   

   • Be sure to read through the best practices and style guidelines in docs/.
   • Test and lint your code! Please see below for a detailed discussion.
   • Ensure compliance with conventional commits, see below. This is enforced by the CI and will prevent your PR from being merged if not followed.

4. Proposed changes are contributed through GitHub Pull Requests.

   • When your contribution is ready and the tests all pass, push your branch to GitHub:

     git push origin <username>/<short-dash-seperated-feature-description>
     

   • Once the branch is uploaded, GitHub will print a URL for submitting your contribution as a pull request. Open that URL in your browser, write an informative title and a detailed description for your pull request, and submit it.

   • Please link the relevant issue (either the existing one or the one you created) to your PR. See the right column on the PR page. Alternatively, in the PR description, mention that it "Fixes link-to-the-issue" - GitHub will do the linking automatically.

   • The team will review your contribution and provide feedback. To incorporate changes recommended by the reviewers, commit edits to your branch, and push to the branch again (there is no need to re-create the pull request, it will automatically track modifications to your branch), e.g.:

     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-description>
     

   • Once your pull request is approved by the reviewers, it will be merged into the main branch in the repository.

Conventional Commits

At Weights & Biases, we ask that all PR titles conform to the Conventional Commits specification. Conventional Commits is a lightweight convention on top of commit messages.

Structure

The commit message should be structured as follows:

<type>(<scope>): <description>

Types

Only certain types are permitted.

Type	Name	Description	User-facing?
feat	✨ Feature	Changes that add new functionality that directly impacts users	Yes
fix	🐛 Fix	Changes that fix existing issues	Yes
refactor	💎 Code Refactor	A code change that neither fixes a bug nor adds a new feature	No
docs	📜 Documentation	Documentation changes only	Maybe
style	💅 Style	Changes that do not affect the meaning of the code (e.g. linting)	Maybe
chore	⚙️ Chores	Changes that do not modify source code (e.g. CI configuration files, build scripts)	No
revert	♻️ Reverts	Reverts a previous commit	Maybe
security	🔒 Security	Security fix/feature	Maybe

Scopes

Which part of the codebase does this change impact? Only certain scopes are permitted.

Scope	Name	Description
sdk	Software Development Kit	Changes that don't fall under the other scopes
integrations	Integrations	Changes related to third-party integrations
artifacts	Artifacts	Changes related to Artifacts
sweeps	Sweeps	Changes related to Sweeps
launch	Launch	Changes related to Launch
leet	LEET	Changes related to W&B LEET TUI

Sometimes a change may span multiple scopes. In this case, please choose the scope that would be most relevant to the user.

Subjects

Write a short, imperative tense description of the change.

User-facing notes (ones with type fix and feat) should be written so that a user can understand what has changed. If the feature or fix does not directly impact users, consider using a different type.

✅ Good Examples

• feat(sdk): add support for RDKit Molecules

  It is clear to the user what the change introduces to our product.

• fix(sdk): fix a hang caused by keyboard interrupt on Windows

  This bug fix addressed an issue that caused the sdk to hang when hitting Ctrl-C on Windows.

❌ Bad Examples

• fix(launch): fix an issue where patch is None

  It is unclear what is referenced here.

• feat(sdk): Adds new query to the internal api getting the state of the run

  It is unclear what is of importance to the user here, what do they do with that information. A better type would be chore or the title should indicate how it translates into a user-facing feature.

Setting up your development environment

The W&B SDK is implemented in Python, Go, and Rust.

Setting up Python

We recommend using uv for Python version management and virtual environments.

To install uv, follow these instructions.

Then install a supported Python version and set up your environment:

uv python install 3.13
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install nox into your environment:

uv pip install nox

Setting up Go

Install Go version 1.26.5 following the instructions here or using your package manager, for example:

brew install go@1.26

Setting up Rust

You will need the Rust toolchain to build the wandb-xpu binary used to monitor hardware accelerators including Nvidia, AMD and Apple Arm GPU, as well as Google TPU. Refer to the official Rust docs and install it by running:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && . "$HOME/.cargo/env"

Building/installing the package

We recommend installing the wandb package in the editable mode:

uv pip install --reinstall --refresh-package wandb -e .

If you are modifying Go or Rust code, you should rerun the command to rebuild and reinstall the package.

Linting the code

We are using prek hooks to manage our linters and other auto-generated code.

To install prek run the following:

uv tool install prek

To install all of our prek hooks run:

prek install

If you just want to run a specific hook, for example formating your code, you could run the following:

prek run ruff-format --all-files --hook-stage pre-push

Auto-Generating Code

Building protocol buffers

We use protocol buffers to communicate from the user process to the wandb backend process.

If you update any of the .proto files in wandb/proto, you'll need to run the proto nox command to build the protocol buffer files:

nox -t proto

Note: you only need to do that if you change any of our protocol buffer files.

Adding a new setting

• Update the wandb/sdk/wandb_settings.py::Settings class.
  • Public settings should be declared as class attributes with optional default value and validator methods.
  • Modifiable settings meant for internal use should be prefixed with x_.
  • Read-only computed settings should be defined as class methods using the @computed_field and @property decorators. If meant for internal use only, should be prefixed with _.
• Add the new field to wandb/proto/wandb_settings.proto following the existing pattern.
  • Run nox -t proto to re-generate the stubs.

Adding URLs (internal use only)

All URLs displayed to the user should be added to wandb/errors/links.py. This will better ensure that URLs do not lead to broken links. You can use the dub.co service to shorten the URLs.

Deprecating features

Starting with version 1.0.0, wandb will be using Semantic Versioning. The major version of the library will be incremented for all backwards-incompatible changes, including dropping support for older Python versions.

Features currently marked as deprecated will be removed in the next major version (1.0.0).

Marking a feature as deprecated

To mark a feature as deprecated and track its usage in telemetry:

1. Add a new boolean field <deprecated_feature> to the Deprecated message in wandb/proto/wandb_telemetry.proto.
2. Rebuild protocol buffer files by running nox -t proto.
3. Call wandb.sdk.lib.deprecation.warn_and_record_deprecation in your code:

from wandb.proto.wandb_telemetry_pb2 import Deprecated
from wandb.sdk.lib.deprecation import warn_and_record_deprecation

warn_and_record_deprecation(
    feature=Deprecated(deprecated_feature=True),  # field name from step 1
    message="This feature is deprecated and will be removed in a future release.",
)

Modifying GraphQL Schema

If there is a schema change on the Server side that affects your GraphQL API, follow the instructions:

• For wandb-core (Go): here
• For wandb (Python):
  • Update the commit hash in ./core/api/graphql/schemas/commit.hash.txt
  • (Re-)run nox -s gql-codegen

Testing

Using pytest

We use the pytest framework. Tests can be found in tests/. All test dependencies should be in requirements/requirements_dev.txt so you could just run:

uv pip install -r requirements/requirements_dev.txt

After that you can run your test using the standard pytest commands. For example:

pytest -s -vv tests/path-to-tests/test_file.py

Running system_tests locally (internal-only)

If you're an internal engineer, launch a local test server:

python tools/local_wandb_server.py start

Now you can run pytest for system_tests.

When you're done, shut it down:

python tools/local_wandb_server.py stop

Archiving server images (internal-only)

The system-tests-min-server-version CI jobs test the SDK against the oldest supported W&B server release. The local-testcontainer images for released server versions are archived in us-central1-docker.pkg.dev/wandb-client-cicd/images/local-testcontainer, because the source registry (wandb-production) only retains images for recent commits.

The archive is updated manually. Whenever you need a release that is not yet archived, run:

go install github.com/google/go-containerregistry/cmd/gcrane@latest
GITHUB_ACCESS_TOKEN=$(gh auth token) nox -s local-testcontainer-registry

This archives the image for the latest wandb/core server release and is a no-op if it is already archived. To archive a specific release instead, pass its tag:

GITHUB_ACCESS_TOKEN=$(gh auth token) nox -s local-testcontainer-registry -- server/v0.81.3

You will need gcloud authenticated with an account that can read wandb-production/images/local-testcontainer and write wandb-client-cicd/images/local-testcontainer.

Troubleshooting

golangci-lint version mismatch

Example:

Error: can't 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: can't load config: the Go language version (go1.25) used to build golangci-lint is lower than the targeted Go version (1.26.2)

Try:

prek cache clean

This will rebuild golangci-lint and may solve the issue.