Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
263 lines (184 loc) · 9.04 KB

CONTRIBUTING.md

File metadata and controls

263 lines (184 loc) · 9.04 KB
Raw

Contributing to OpenAI Java SDK

Setting up the environment

This repository uses Gradle with Kotlin DSL for building and dependency management. The framework-neutral SDK requires Java 8, while development requires JDK 21 for the Kotlin toolchain. See the Java version support policy for artifact-level runtime, framework, lifecycle, and release rules.

Project structure

The SDK's primary artifacts are:

  • openai-java-core
  • openai-java-client-okhttp
  • openai-java
    • Depends on and exposes the APIs of both openai-java-core and openai-java-client-okhttp
    • Does not have its own logic
  • openai-java-bedrock
    • Adds optional Amazon Bedrock authentication and credential-provider integration
  • openai-java-spring-boot-starter
    • Provides the legacy Spring Boot 2 integration
    • Is retained to verify the final 4.45.0 release, but is OpenAI EOL and no longer published

openai-java-runtime-compatibility is a non-published fixture that exercises representative behavior for each supported artifact on an isolated runtime classpath. Its JVM matrix and each artifact's eligibility on a given JVM come from gradle/version-support.properties.

Modifying or adding code

Most of the SDK is generated code. Modifications to code will be persisted between generations, but may result in merge conflicts between manual patches and changes from the generator. The generator will never modify the contents of the openai-java-example/ directory.

Adding and running examples

All files in the openai-java-example/ directory are not modified by the generator and can be freely edited or added to.

// openai-java-example/src/main/java/com/openai/example/YourExample.java
package com.openai.example;

public class YourExample {
    public static void main(String[] args) {
        // ...
    }
}
$ ./gradlew :openai-java-example:run -PmainClass=com.openai.example.YourExample

Using the repository from source

If you'd like to use the repository from source, you can either install from git or link to a cloned repository.

To use a local version of this library from source in another project, you can publish it to your local Maven repository:

$ ./gradlew publishToMavenLocal

Note

For now, to publish locally, you'll need to comment out the line for signAllPublications() here: buildSrc/src/main/kotlin/openai.publish.gradle.kts

Then in your project's build.gradle.kts or pom.xml, reference the locally published version:

implementation("com.openai:openai-java:2.9.1")
<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>2.9.1</version>
</dependency>

Alternatively, you can build and install the JAR files directly:

$ ./gradlew build

JAR files will be available in each module's build/libs/ directory.

Running tests

Most tests require our mock server to be running against the OpenAPI spec to work.

The test script will automatically start the mock server for you (if it's not already running) and run the tests against it:

$ ./scripts/test

You can also manually start the mock server if you want to run tests repeatedly:

$ ./scripts/mock

Then run the tests:

$ ./scripts/test

Test configuration

  • Tests run in parallel for better performance
  • Mock server runs on localhost:4010
  • You can disable mock server tests with SKIP_MOCK_TESTS=true
  • You can target a custom API URL with TEST_API_BASE_URL=<url>

Testing framework

The project uses:

  • JUnit 5 for test framework
  • Mockito for mocking
  • AssertJ for fluent assertions
  • WireMock for HTTP service mocking
  • Custom TestServerExtension for mock server management

Linting and formatting

This repository uses Spotless with Palantir Java Format for code formatting and various linting tools.

To check formatting and run lints:

$ ./scripts/lint

This will compile all modules and run static analysis checks.

To fix all formatting issues automatically:

$ ./scripts/format

You can also check formatting directly with Gradle:

$ ./gradlew spotlessCheck  # Check formatting

Building

To build all modules:

$ ./gradlew build

To build a specific module:

$ ./gradlew :openai-java-core:build

Adding and running examples

All files in the openai-java-example/ directory are not modified by the generator and can be freely edited or added to.

// add an example to openai-java-example/src/main/java/com/openai/example/<YourExample>.java

package com.openai.example;

public class YourExample {
    public static void main(String[] args) {
        // ...
    }
}

Publishing and releases

Changes made to this repository via the automated release PR pipeline should publish to Maven Central automatically. If the changes aren't made through the automated pipeline, you may want to make releases manually.

Publish with a GitHub workflow

You can release to package managers by using the Publish Sonatype GitHub action. This requires the GitHub publish environment to be configured.

The publish environment must have these environment secrets:

  • OPENAI_SONATYPE_USERNAME - The username from a Central Portal user token
  • OPENAI_SONATYPE_PASSWORD - The password from a Central Portal user token
  • OPENAI_SONATYPE_GPG_SIGNING_KEY - The ASCII-armored GPG private key used for signing artifacts
  • OPENAI_SONATYPE_GPG_SIGNING_PASSWORD - The GPG key passphrase

To rotate credentials, generate a new Central Portal user token and update OPENAI_SONATYPE_USERNAME and OPENAI_SONATYPE_PASSWORD. If rotating the signing key, generate a passphrase-protected GPG key and publish the public key:

$ gpg --quick-gen-key "OpenAI Maven Central <maintainer@openai.com>" rsa4096 sign 0
$ gpg --list-secret-keys --keyid-format LONG
$ gpg --armor --export-secret-keys KEY_ID > openai-sonatype-signing-key.asc
$ gpg --keyserver keyserver.ubuntu.com --send-keys KEY_ID

The 0 makes the key non-expiring. KEY_ID is the value after the slash on the sec line from gpg --list-secret-keys, for example 42B825E73825CCEB in sec rsa4096/42B825E73825CCEB. The GPG email does not need to match the Central Portal token account.

$ gh secret set OPENAI_SONATYPE_USERNAME --env publish --repo openai/openai-java
$ gh secret set OPENAI_SONATYPE_PASSWORD --env publish --repo openai/openai-java
$ gh secret set OPENAI_SONATYPE_GPG_SIGNING_KEY --env publish --repo openai/openai-java < openai-sonatype-signing-key.asc
$ gh secret set OPENAI_SONATYPE_GPG_SIGNING_PASSWORD --env publish --repo openai/openai-java

After the rotated secrets work, revoke the old Central Portal token and remove any old repository-level copies of the OPENAI_SONATYPE_* secrets.

Publish manually

If you need to manually release a package, you can run:

$ ./gradlew publishAndReleaseToMavenCentral \
    -PmavenCentralUsername="$SONATYPE_USERNAME" \
    -PmavenCentralPassword="$SONATYPE_PASSWORD"

This requires the following environment variables to be set:

  • SONATYPE_USERNAME - The username from a Central Portal user token
  • SONATYPE_PASSWORD - The password from a Central Portal user token
  • GPG_SIGNING_KEY - Your ASCII-armored GPG private key for signing artifacts
  • GPG_SIGNING_PASSWORD - Your GPG key passphrase

Development tools

Available gradle tasks

Some useful Gradle tasks:

$ ./gradlew tasks               # List all available tasks
$ ./gradlew build               # Build all modules
$ ./gradlew test                # Run all tests
$ ./gradlew spotlessApply       # Format code
$ ./gradlew publishToMavenLocal # Publish to local Maven repository
$ ./gradlew dependencies        # Show dependency tree