Skip to content

pitfalls.md

Latest commit

 

History

History
15 lines (8 loc) · 1.53 KB

pitfalls.md

File metadata and controls

15 lines (8 loc) · 1.53 KB
Raw

Common Pitfalls

  1. Editing Fern-generated files directly. Any file with the /** This file was auto-generated by Fern ... */ header that is not listed in .fernignore is regenerated on the next SDK build — your edit is silently lost. Fix the Fern API spec or the generators/java-v2 generator instead, or move the file's logic into a hand-maintained (.fernignore) location. This is the single most common mistake in this repo.

  2. Assuming .fernignore covers the whole Management API. It protects only the explicitly listed files/dirs (the Authentication API, net/, exception/, utils/, json/auth/, the custom builders/token providers, and specific tests). Everything else under the generated mgmt tree is fair game for regeneration.

  3. Using post-Java-8 syntax. The library compiles and runs on Java 8 (sourceCompatibility = 1.8, toolchain pinned to 8). No var, records, sealed types, or switch expressions in src/.

  4. Skipping spotlessApply. CI's check includes spotlessCheck (palantir-java-format). Unformatted code fails the build even if tests pass.

  5. Introducing breaking changes. This is a widely-consumed published library. Source/binary-breaking changes require explicit approval and a migration-guide entry — see Boundaries in CLAUDE.md.

  6. Hardcoding a real tenant/secret. Never put a real Auth0 domain, client secret, or token into code, tests, fixtures, or the sample app.

  7. Hand-editing reference.md. It is large and generated; regenerate rather than edit.