Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (51 loc) · 5.66 KB

AGENTS.md

File metadata and controls

75 lines (51 loc) · 5.66 KB

Agents

Fern SDK Regeneration

Overview

This SDK is generated by Fern. Most files under src/main/java/com/deepgram/ are auto-generated and should not be edited directly. Some files are hand-written or carry manual patches and are listed in .fernignore to prevent the generator from overwriting them.

When a new Fern generator release is available, we prepare the repo so the generator can overwrite previously frozen files, then re-apply manual patches after reviewing the diff.

Freeze classification rules

Every entry in .fernignore falls into one of two categories. The comment above each entry in .fernignore indicates which category it belongs to, but when in doubt, apply these rules:

Never unfreeze (permanently frozen)

These files are entirely hand-written or are maintained independently from Fern. The generator would delete or replace them with something unrelated. They must stay in .fernignore at all times.

How to identify:

  • The file was created by us, not by Fern, such as custom client wrappers or transport abstractions
  • The file is a doc, config, build, or CI artifact we maintain independently
  • The file lives outside the generated Java package tree or is a manually maintained test/example

Current permanently frozen files:

  • src/main/java/com/deepgram/DeepgramClient.java, src/main/java/com/deepgram/AsyncDeepgramClient.java, src/main/java/com/deepgram/DeepgramClientBuilder.java, src/main/java/com/deepgram/AsyncDeepgramClientBuilder.java - custom wrapper entrypoints that add Bearer auth, session ID support, and custom transport behavior on top of Fern's generated API client
  • src/main/java/com/deepgram/core/transport/ - hand-written transport abstraction
  • build.gradle, settings.gradle, gradle/, gradlew, gradlew.bat, pom.xml, Makefile - build and project configuration
  • README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE, docs/ - docs
  • src/test/ - manually maintained tests
  • examples/ - manually maintained examples
  • .editorconfig, .githooks/, .github/, .gitignore - repo and CI configuration
  • target/ - build output
  • CLAUDE.md, AGENTS.md, .claude/ - agent files

Note: .fernignore also includes flat-path variants such as src/main/java/DeepgramClient.java as defensive entries for alternate local generation layouts. Those files do not currently exist in this repo checkout and should not be treated as current maintained source files.

Unfreeze for regen (temporarily frozen)

These files are Fern-generated but carry manual patches to fix issues in the generator output. We freeze them to protect our patches between regenerations, but unfreeze them before a regen so we can compare the new output against our patches.

How to identify:

  • The file exists in Fern's output - if you removed it from .fernignore and ran the generator, Fern would produce a version of it
  • Our version is a modified copy of what Fern generates

Current temporarily frozen files:

  • src/main/java/com/deepgram/core/ClientOptions.java - preserves release-please version markers and correct SDK header constants that Fern currently overwrites; use the standard .bak swap/restore workflow during regen review
  • src/main/java/com/deepgram/core/ReconnectingWebSocketListener.java - carries bug fixes for maxRetries(0) semantics ("connect once, don't retry") and a configurable connectionTimeoutMs field (was hardcoded 4000ms), plus an applyOptionsOverride(...) hook used by TransportWebSocketFactory to apply per-transport reconnect policy; pull this back out once the fixes are upstreamed into the Fern generator. Use the standard .bak swap/restore workflow during regen review.

Prepare repo for regeneration

  1. Create a new branch off main named lo/sdk-gen-<YYYY-MM-DD>.
  2. Push the branch and create a PR titled chore: SDK regeneration <YYYY-MM-DD> (empty commit if needed).
  3. Read .fernignore and classify each entry using the rules above.
  4. For each temporarily frozen file only:
    • Copy the file to <filename>.bak alongside the original.
    • In .fernignore, replace the original path with the .bak path. This protects our patched version from the generator while allowing Fern to overwrite the original.
  5. Never touch permanently frozen entries. Leave them in .fernignore as-is.
  6. Commit as chore: unfreeze files pending regen and push.
  7. The branch is now ready for the Fern generator to push changes.

After regeneration

The .bak files are our manually patched versions protected by .fernignore. The original paths now contain the freshly generated versions. By comparing the two, we can see what the generator now produces versus what we had patched.

  1. Diff each .bak file against the new generated version to understand what changed and whether our patches are still needed.
  2. Re-apply any patches that are still necessary to the newly generated files. For src/main/java/com/deepgram/core/ClientOptions.java, use the standard .bak restore flow if the generated output still overwrites the Deepgram SDK header constants and // x-release-please-version markers.
  3. In .fernignore, replace each .bak path back to the original path for files that still need patches.
  4. Remove .fernignore entries entirely for any files where the generator now produces correct output.
  5. Delete all .bak files once review is complete.
  6. Run checks (./gradlew test compileExamples) to verify. test covers unit/wire tests including the README snippet compilation; compileExamples separately compiles the hand-maintained examples/ directory and catches stale API call sites that test alone would miss.
  7. Commit as chore: re-apply manual patches after regen and push.