Manage Deprecations

Deprecation Cleanup

Quarkus accumulates @Deprecated code over time. This skill covers three workflows, sharing one discovery tool and the same commit/annotation conventions:

• Removal — code deprecated for at least 12 months (the project's convention) is safe to delete; keeping it forever defeats the point of deprecating it.
• Completion — when one element is deprecated, everything that only exists to serve it should be deprecated too. A common miss: a field is marked @Deprecated but its getter, setter, constructor parameter, or builder method is not, so callers using the accessors get no warning.
• New deprecation — the user asks to deprecate some category of element outright, e.g. "deprecate constructors of classes with a builder". This is a fresh deprecation, not a gap-fill, but it uses the same annotation conventions as Completion (see below).

The discovery tool

scripts/find-deprecated.sh scans Java files for @Deprecated and prints each entry sorted by the date it was originally introduced. It uses git blame -w -M -C -C -C so a line's date reflects when it was first written, not when a later refactor moved it — so the 12-month clock runs from the real introduction date. Run it from the skill's scripts/ directory (or use the full path):

scripts/find-deprecated.sh core/deployment --removable --csv          # Workflow A: only entries ≥12 months old
scripts/find-deprecated.sh core/deployment --csv                      # Workflow B: ALL deprecations (default)
scripts/find-deprecated.sh core/deployment --min-age-months=18 --csv  # custom threshold

--csv emits CSV (easier to sort/filter) instead of the formatted table; redirect to $TMPDIR to avoid re-scanning. Columns: File Location (path:line), Deprecated Entry (the declaration), Date (YYYY-MM-DD introduced), Commit (short hash).

Scan the narrowest path that covers the request — the whole repo is slow (one git blame per hit).

Workflow A — Remove long-deprecated code

The rule is age-based, but age alone is not sufficient to delete safely. Removal of a public API can break callers, so verify before you cut.

1. Discover the removal candidates

Run --removable (see above); the list it prints is already the candidate set. Entries dated unknown (blame couldn't resolve) are excluded because their age can't be confirmed — run without --removable to review those individually.

2. Confirm each candidate is genuinely safe to remove

For every candidate, before deleting:

• Search the whole repo for remaining usages of the symbol (method name, constructor signature, field). Include tests, integration-tests, and docs. Deprecated does not mean unused.
• If usages remain, they were supposed to migrate to the replacement named in the @deprecated javadoc. Migrate them first (in the same change), or, if migration is non-trivial or out of scope, leave that entry in place and move on — don't delete something the codebase still depends on.
• Watch for overrides and API contracts: a deprecated method may implement an interface or be overridden elsewhere; removing it can break the hierarchy.

If in doubt about whether an external/public API can be dropped, surface it to the user rather than guessing — some deprecated items are kept intentionally for downstream compatibility.

3. Remove, one class per change

Delete the declaration and its javadoc/annotation block together. Preserve surrounding comments that are not about the removed element (see the repo's editing rules). Group all removals within a single class into one commit; keep different classes in separate commits so history stays reviewable.

4. Build the affected module

Removing code can break compilation elsewhere in the module (or its dependents). Build the module you touched — and rebuild its deployment module if you changed a runtime module (see the building-and-testing skill):

./mvnw install -f <module-path> -DskipTests

Fix any fallout (usually leftover callers you can migrate to the replacement). Only consider the removal done once it compiles.

5. Commit

One commit per class. See Commit conventions below.

Workflow B — Complete missed deprecations

When you deprecate something, its satellites should be deprecated too. The classic gap is a deprecated field whose accessors (getter/setter), constructors, or builder methods were left un-annotated — so a caller using the getter gets no warning.

1. Find the gaps

Run the tool without an age filter (the default) so every deprecation shows up regardless of when it was introduced — the gaps you're hunting for are often recent:

scripts/find-deprecated.sh <path> --csv

While reviewing a class (or when the user reports one), look for a deprecated element whose companions are not deprecated:

• A @Deprecated field → is its getter/setter deprecated? Its constructor parameter? The builder method that sets it?
• A @Deprecated constructor/method → do overloads that only forward to it, or builder entry points that only exist for it, still lack the annotation?

git blame the un-annotated companion to understand when it was introduced and whether it was meant to be deprecated alongside the element it serves. The commit that deprecated the primary element is your reference.

2. Add the annotation + javadoc

Add both an @Deprecated annotation and a javadoc @deprecated tag that tells the user what to use instead. The javadoc is what makes the deprecation actionable — without a replacement pointer it's just noise.

/**
 * @deprecated Use {@link GeneratedResourceBuildItem#GeneratedResourceBuildItem(String, byte[])} instead.
 *             If you want to serve static resources use
 *             {@link io.quarkus.vertx.http.deployment.spi.GeneratedStaticResourceBuildItem} instead.
 */
@Deprecated(since = "4.0")
public GeneratedResourceBuildItem(String name, byte[] data, boolean excludeFromDevCL) {
    ...
}

3. Build and commit

Build the module (Workflow A, step 4) and commit — message form "Code deprecation in X" (see below).