Skip to content

Latest commit

 

History

History
206 lines (150 loc) · 6.68 KB

CONTRIBUTING.md

File metadata and controls

206 lines (150 loc) · 6.68 KB

Contributing to weave

Issues

  1. Check the issues and PRs to see if the feature/bug has already been requested/fixed. If not, open an issue. This helps us keep track of feature requests and bugs!

  2. If you're having issues, the best way we can help is when you can share a reproducible example.

    1. In general, it's helpful to use this format:

      <short description of the issue>
<link to your project>
<system info, including weave version, python version, and OS>

<reproducible code snippet>

<any other info you think is relevant>

    2. For SDK issues, a reproducible script like example_error_script.py is helpful. We use uv which can run the script with the dependencies included. If you know the dependencies, you can add them to the script. See the uv docs for more details.

PRs

  1. If you are a first-time contributor, welcome! To get started, make a fork and point to the main weave repo: 
    git clone https://github.com/<your-username>/weave.git
cd weave
git remote add upstream https://github.com/wandb/weave.git
  2. Build!
    1. Keep your fork up to date with the main weave repo: 
      git checkout master
git pull upstream master
    2. Create a branch for your changes: 
      git checkout -b <your-username>/<your-branch>
    3. Commit changes to your branch and push: 
      git add your_file.py
git commit -m "feat(integrations): Add new integration for <your-package>"
git push origin <your-username>/<your-branch>
    4. Open a PR!

Conventional Commits

All PR titles should conform to the Conventional Commits spec. Conventional Commits is a lightweight convention on top of commit messages.

Structure

The commit message should be structured as follows:

<type>(<scope>): <description>
⭐ **TLDR:** Every commit that has type `feat` or `fix` is **user-facing**. If notes are user-facing, please make sure users can clearly understand your commit message.

Types

Only certain types are permitted.

⭐ User-facing notes such as `fix` and `feat` should be written so that a user can clearly understand the changes. If the feature or fix does not directly impact users, consider using a different type. Examples can be found in the section below.
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
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

Setting up your environment

We use:

  1. uv for package and env management -- follow the uv guide to bootstrap an environment 
    curl -LsSf https://astral.sh/uv/install.sh | sh
  2. nox for running tests 
    uv tool install nox

Working with the weave package

We recommend installing the package in editable mode:

uv pip install -e .

Linting

We use pre-commit. You can install with:

uv tool install pre-commit

Then run on staged files (default, faster):

pre-commit run --hook-stage=pre-push

Or run on all files (slower but more thorough):

pre-commit run --hook-stage=pre-push --all-files

You can also use the lint nox target to run linting:

# Run on staged files only (default, faster)
nox -e lint

# Run on all files
nox -e lint -- --all-files

Building the weave package

Use uv:

uv build

Testing

We use pytest and nox to run tests. To see a list of test environments:

nox -l

Then to run a specific environment:

nox -e "$TARGET_ENV"  # e.g. nox -e "tests-3.12(shard='trace')"

Tests are split up into shards, which include:

  1. trace -- all of the trace SDK tests
  2. trace_server -- tests for trace server backend
  3. various integrations, like openai, instructor, etc -- these envs are isolated to simplify testing

Nox is the most thorough way to run the tests, as it sets important environment variables needed to run specific integrations and shards. However, it is slower. A combination of uv and pytest can be used for faster iteration when your code is agnostic to integration type, python version, etc.

uv sync --group test --active
uv run pytest

For even faster iteration, it is possible to limit scope to a single file or test. For example:

uv run pytest tests/trace/test_weave_client.py

or

uv run pytest tests/trace/test_weave_client.py::test_table_create

Deprecating features

weave is moving quickly, and sometimes features need to be deprecated.

To deprecate a feature, use the deprecated decorator from weave.trace.util. This is currently used primarily for renames.

from weave.trace.util import deprecated

@deprecated("new_func_name")
def old_func():
    pass