Deprecate CaffeineCacheStats.registerCache

[ash211]

Before this PR

We added an improved mechanism for registering stats on a cache in #1897, with a few FLUPs (linked at the bottom of that PR). The new method is also documented in the tritium README here.

However, existing code is still using the old mechanism, and callers who forgot to call .recordStats() are still being found (we noticed several this week).

After this PR

==COMMIT_MSG==
Deprecate CaffeineCacheStats.registerCache
==COMMIT_MSG==

By marking this method as deprecated, we nudge developers who see these warnings in their IDE towards the preferred pattern.

Possible downsides?

Repos that have opted into making deprecations fail builds and are using these now-deprecated methods won't be able to take the upgrade automatically. However, this something those repos have opted into and should expect as a result of that choice.

[changelog-app]

Generate changelog in changelog/@unreleased

What do the change types mean?

• feature: A new feature of the service.
• improvement: An incremental improvement in the functionality or operation of the service.
• fix: Remedies the incorrect behaviour of a component of the service in a backwards-compatible way.
• break: Has the potential to break consumers of this service's API, inclusive of both Palantir services
  and external consumers of the service's API (e.g. customer-written software or integrations).
• deprecation: Advertises the intention to remove service functionality without any change to the
  operation of the service itself.
• manualTask: Requires the possibility of manual intervention (running a script, eyeballing configuration,
  performing database surgery, ...) at the time of upgrade for it to succeed.
• migration: A fully automatic upgrade migration task with no engineer input required.

Note: only one type should be chosen.

How are new versions calculated?

• ❗The break and manual task changelog types will result in a major release!
• 🐛 The fix changelog type will result in a minor release in most cases, and a patch release version for patch branches. This behaviour is configurable in autorelease.
• ✨ All others will result in a minor version release.

Type

• Feature
• Improvement
• Fix
• Break
• Deprecation
• Manual task
• Migration

Description

Deprecate CaffeineCacheStats.registerCache

Check the box to generate changelog(s)

• Generate changelog entry

[carterkozak]

How widely is this API still used? How many of those repos compile with -Werror? We should take deprecation seriously -- unless humans are keeping a close eye on upgrade PRs, this will prevent those projects from taking almost all first party library upgrades until humans intervene!

[ash211]

How widely is this API still used? How many of those repos compile with -Werror? We should take deprecation seriously -- unless humans are keeping a close eye on upgrade PRs, this will prevent those projects from taking almost all first party library upgrades until humans intervene!

I discussed this in the PR description:

Repos that have opted into making deprecations fail builds and are using these now-deprecated methods won't be able to take the upgrade automatically. However, this something those repos have opted into and should expect as a result of that choice.

I count 575 callsites internally: https://pl.ntr/2ok. This deprecation would only affect repos that have -Werror AND -Xlint:deprecation enabled. The first is enabled in the new default for highline-created repos now, as of March: 0682272. But the second is not, and is less widely deployed (140+ internal repos).

Personally I think -Xlint:deprecation causes more problems than it's worth, and it's not enabled on most repos I regularly work with. There needs to be a way to noticeably signal that something is going away, WITHOUT requiring that it happen immediately. @Deprecation annotation is that, unless -Xlint:deprecation is turned on. A Javadoc @deprecated isn't loud enough in IDEs.