Add Java SDK generator v5 migration guide

[nerminamiller-postman]

Summary

Adds a hidden generators/java/migration-v5.mdx page (nav entry hidden: true) adapted from two internal SDKGEN Confluence guides: "Java Migration Guide" (synced to version 69) and "Java - WebSockets Migration Guide". Same pattern as the Go (#7154) and Swift (#7155) pages.

• Version 5.0.0 is the Java cutover version in generatorConfigPolicy.ts in the CLI.
• The WebSocket items, which v69 moves into the main guide (items 6–14), are a final "WebSocket channels" section.
• Synced with v69:
  • Request wrapper names are verb-first by default (idiomatic-request-names: true). There's a new <Warning> to set package-prefix so the root package doesn't change (FSDK-2010).
  • Build/docs: documentation/ becomes reference.md, and there's an opt-in generateTests.
  • Removed the items marked ✅ fixed: pattern-keyed maps as Object, OptionalNullable → Optional, the OkHttp downgrade, and the socket client/handler renames. Also removed nested-type and merged-control-frame items, which aren't in the current guide.
• WebSocket discriminator, corrected by @shraddha-postman against real generated output (three SDKs, 56 frame classes), overriding the internal guide:
  • getType() stays String before and after v5; the only change is that type is no longer duplicated into the additional-properties map.
  • Removed "Send frames require the discriminator"; no generated send-frame builder requires .type(...).
• Left out (❗ known gaps, not migration steps): feat: new home page #2 (some types and methods not generated yet), the customer-specific name differences in Add revamped Typescript Quickstart page #4, and Feat add homepage #6 (a channel bound to a non-default host ignores the configured environment). If these aren't fixed by launch, add a <Warning>.

Reviewer checks:

• Confirm that validateResponses, idiomatic-request-names, and generateTests are the user-facing config keys.
• The internal guide still describes getType() as an enum and send frames as requiring type. Update it so later syncs don't bring those back.

Link to Devin session: https://app.devin.ai/sessions/f35ec303b4df4315ae1ecfffa28c3295
Open in Devin Desktop: https://app.devin.ai/desktop/session/f35ec303b4df4315ae1ecfffa28c3295?variant=devin
Requested by: @nerminamiller-postman

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1790634233-java-v5-migration-guide.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/sdks/generators/java/migration-v5

[shraddha-postman]

Pushed a correction to the WebSocket section, checked against Fern's real generated output (deepgram_bundled, basis_theory, bloomberg_sse_spec — 56 frame classes with a type discriminator, not just one example):

• getType() returns String before and after v5 — it never becomes an enum. Only change: type stops being duplicated into the additional-properties map.
• Removed "Send frames require the discriminator" — none of the 56 classes checked, nor any of the 38 that do require some other field first, require .type(...). Couldn't find a case where this is true, so I don't think it's a real v5 change.

Happy to share the generated SDKs I checked this against if useful.

[github-actions]

📝 [vale] <FernStyles.Adverbs> _{reported by reviewdog 🐶}
Remove 'silently' if it's not important to the meaning of the statement.

Suggested change

	When the SDK runs out of reconnection attempts, it passes an `IllegalStateException` to your error handler instead of stopping silently. The same `maxRetries` value makes one more attempt than before.
	When the SDK runs out of reconnection attempts, it passes an `IllegalStateException` to your error handler instead of stopping . The same `maxRetries` value makes one more attempt than before.

[devin-ai-integration]

Thanks for checking this against generated output. I looked over your commit (71d0ce8), and Vale and CI pass. I also updated the PR description: it no longer says getType() returns an enum or that send frames need type. The internal Java guide still says both, so it's worth correcting there too, or a later sync could bring them back.