CSR FAQ item on deprecation

[Stuart Marks]

On 4/20/17 9:42 AM, joe darcy wrote:
> Paging Dr. Deprecator!
>
> Consultation on deprecation needed; please review the draft CSR FAQ item on
> deprecation.
>
> Thanks,
>
> -Joe
>
> Q: What is the JDK's policy on deprecating items?
> A: As of JDK 9, JDK APIs use enhanced deprecation
> (http://openjdk.java.net/jeps/277). In summary, if an API is problematic in one
> or more ways, it can be marked as @Deprecated to discourage its use. If there
> are plans to remove the API in the following release, then it should be marked
> as @Deprecated(forRemoval=true). If an item is deprecated for removal in the
> next release, the bug to implement the removal should be filed by the time the
> CSR request is approved. Deprecated items should have a corresponding
> @deprecated javadoc tag.

Hi Joe,

This is a pretty good answer. I'd only add that the text for the @deprecated 
javadoc tag should include a recommendation for a replacement API, and any 
potential issues (e.g., semantic differences) with substituting it.

s'marks