CSR FAQ item on deprecation

[Joseph D. Darcy]

On 4/21/2017 12:48 PM, Stuart Marks wrote:
> 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

Thanks Stuart; suggested notes on @deprecated added.

Cheers,

-Joe