Coding

Coding (Micronaut Committer)

Use this skill for maintainer-facing Java implementation work in Micronaut repositories. Do not default to end-user application shortcuts.

Goal

Deliver minimal, source-backed Java changes that preserve framework quality: binary compatibility, JSpecify null-safety, reflection-free behavior, and full Gradle verification (check, docs, and compatibility checks when API-facing).

Trigger Examples

Should trigger:

• "Implement this Micronaut Java feature in src/main/java and keep API compatibility."
• "Refactor this module internals and mark non-public APIs correctly."
• "Fix failing framework tests and prepare committer-ready validation output."
• "Add configuration support using Micronaut conventions, not app-level shortcuts."

Should not trigger:

• "Explain Micronaut basics to a beginner."
• "Create an end-user sample app from scratch."
• "Only edit release notes/changelog text."

Procedure

1. Establish scope and API impact.
2. Implement Java code with Micronaut maintainer conventions.
3. Enforce API boundaries and binary compatibility.
4. Document Java APIs and implementation intent.
5. Keep Gradle/build changes aligned with repository conventions.
6. Verify with maintainer-grade checks before completion.

1) Establish scope and API impact

• Identify affected modules and whether any change is public API or internal-only.
• Inspect existing package patterns before editing (imports, nullability style, tests, naming).
• For API-facing edits, plan compatibility checks up front (japiCmp).
• Keep change surface minimal; avoid opportunistic refactors unless required.

2) Implement Java with Micronaut maintainer conventions

• Prefer modern Java idioms where they improve clarity (records, sealed types, pattern matching, var for local inference), but only when supported by the repository toolchain/target level.
• Do not use fully qualified class names unless import conflicts force it.
• Micronaut Java code uses JSpecify nullness annotations from org.jspecify.annotations; use JSpecify for new or modified nullability contracts.
• New Java packages must include package-info.java with @NullMarked and import org.jspecify.annotations.NullMarked; when touching an existing package without @NullMarked, add it unless the local code has an explicit exception.
• Use org.jspecify.annotations.Nullable for nullable values, including nullable parameters, return values, fields, array/component positions such as String @Nullable [], nullable collection elements such as List<@Nullable T>, and nullable type bounds such as <T extends @Nullable Object>.
• Preserve existing nullability intent when editing older code. Use JSpecify for new or modified contracts, but do not rewrite deliberate compatibility annotations such as io.micronaut.core.annotation.Nullable or jakarta.annotation.Nullable unless the task is specifically a nullability migration and compatibility impact has been checked.
• Avoid reflection-oriented implementations in framework code paths; prefer Micronaut compile-time/introspection mechanisms.
• Use jakarta.inject APIs for DI, not javax.inject.
• Prefer constructor injection and immutable state over field injection.
• For configuration models, prefer @ConfigurationProperties over scattered @Value usage.

3) Enforce API boundaries and compatibility

• Treat all public-facing changes through a Semantic Versioning lens (https://semver.org/) before implementation.
• Classify impact explicitly: patch for backward-compatible fixes, minor for backward-compatible feature additions, major for breaking API/behavioral changes.
• Keep public API binary compatible unless a major-version change explicitly allows breaks.
• Prefer non-breaking API evolution first: deprecate existing methods and add replacement variants/overloads instead of deleting methods or changing signatures in place.
• When using the deprecate-and-add path, keep deprecated APIs functional, point to replacements in Javadoc, and schedule removals only for the next major version.
• If breaking public-facing changes are explicitly allowed, document them in the user guide under src/main/docs/guide with migration notes, and update toc.yml when adding new guide sections.
• Mark non-user-facing APIs with @io.micronaut.core.annotation.Internal.
• Mark unstable public APIs with @io.micronaut.core.annotation.Experimental and avoid presenting them as stable contracts.
• Mark members directly called by generated code with @io.micronaut.core.annotation.UsedByGeneratedCode; preserve those signatures unless the generated-code callers are updated in the same change.
• Keep visibility as narrow as possible for non-public internals.
• When deprecating API, provide migration-friendly Javadoc and avoid silent behavioral breaks.

4) Document Java APIs and implementation intent

• All public Java types and public methods must have Javadoc. Include public constructors when they are part of the user-facing API.
• All new public Java types, methods, and user-facing constructors must include an @since Javadoc tag for the version where the PR will debut.
• Determine the @since version from the approved target branch, not from guesswork. Inspect that branch's gradle.properties (projectVersion) and use the corresponding release version; for example, 4.9.0-SNAPSHOT means the new API debuts in 4.9.0.
• If the PR is retargeted during follow-through, re-check the target branch's gradle.properties and update any newly added @since tags when the debut version changes.
• Do not add @since tags to internal-only APIs annotated with @Internal unless the repository already does so for that internal package.
• Internal and package-private methods should include maintainer-focused Javadoc when the implementation contract, lifecycle, invariants, or generated-code interaction is not obvious from the signature.
• Complex new code should include focused inline comments that explain implementation decisions or invariants; do not narrate straightforward control flow.