langsmith-java/CONTRIBUTING.md

Contributing

Thanks for your interest in contributing to the LangSmith Java SDK!

Overview

This SDK is auto-generated by Stainless from our OpenAPI spec. Custom code (prompts, OTel wrappers, etc.) lives alongside generated code — Stainless is configured to preserve custom code and never overwrite it.

Important: Most files in the SDK are generated. If you need to change generated code, talk to @edongashi — there may be weird errors in the Stainless config, but they're generally fixable.

Branching and workflow

Branch	Purpose
next	Development branch. All PRs should target next.
main	Release branch. Only updated via release-please.
release-please--branches--main--changes--next	Auto-generated release PR. Merges next → main.

Always work off next. Do not merge directly to main — Dependabot or other bots occasionally violate this, which can cause headaches.

Release process

1. Merge your PR into next.
2. A release-please PR is automatically created/updated (release-please--branches--main--changes--next).
3. Verify your change appears in the release PR diff and description.
4. Approve the release PR — it auto-merges on approval.
5. A GitHub Action publishes to Maven Central via ./gradlew publishAndReleaseToMavenCentral.
6. Maven Central can be slow to index — verify on repo1.maven.org rather than mvnrepository.com, which lags behind.

Note: If lint fixes or other changes are pushed to the release-please branch after a version bump, the publish action can fail. Always ensure CI is green before approving.

Development setup

Prerequisites

• Java 8+ (tested against 8 and 21)
• Gradle (uses the included gradlew wrapper)

Building

./scripts/build

Formatting

The project uses ktfmt (--kotlinlang-style) for Kotlin and Palantir Java Format for Java.

# Format all files
./scripts/format

# Format only Kotlin
./gradlew formatKotlin

# Format a single module
./gradlew :langsmith-java-core:formatKotlin

Linting

# Lint all files
./scripts/lint

# Lint only Kotlin
./gradlew lintKotlin

CI blocks on lint failures. Always run ./scripts/format before pushing.

Testing

# Run all tests
./scripts/test

# Run specific tests
./gradlew :langsmith-java-core:test --tests "com.langchain.smith.prompts.*"

# Force re-run (skip Gradle cache)
./gradlew :langsmith-java-core:test --tests "..." --rerun

# See stdout output
./gradlew :langsmith-java-core:test --tests "..." --rerun --info

Integration tests

Integration tests require API keys and skip gracefully via assumeTrue if they're missing:

export LANGSMITH_API_KEY="lsv2_pt_..."
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

CI

CI runs three jobs on every push and PR:

1. lint — ./scripts/lint
2. build — ./scripts/build
3. test — ./scripts/test

All three must pass before merging.

Code style

See AGENTS.md for detailed Kotlin conventions, including:

• Prefer buildMap/buildList over mutable collections
• Use partition instead of double filter
• Use parameterized tests for table-driven cases
• Avoid @Suppress("UNCHECKED_CAST") — restructure with safe casts
• toString() should follow the ClassName{field=value} convention

Dependencies

• Anthropic SDK is a compileOnly dependency — users must add it themselves. Methods using Anthropic types should catch NoClassDefFoundError and throw IllegalStateException with a clear message.
• SLF4J (slf4j-api) is an api dependency for logging. Tests use slf4j-simple.
• Jackson 2.22.0 is the default, but the SDK is compatible with 2.13.4+.