RFR: 8253455: Record Classes javax.lang.model changes [v5]

[Alex Buckley]

On 9/30/2020 2:29 PM, Joe Darcy wrote:
>>> Vicente Romero has updated the pull request incrementally with one 
>>> additional commit since the last revision:
>>>
>>>    adding a comment to PreviewFeature.Feature
>> src/java.compiler/share/classes/javax/lang/model/element/ElementKind.java 
>> line 114:
>>
>>> 112:     /**
>>> 113:      * A record type.
>>> 114:      * @since 14
>> The `@since` tags will all need to be updated to `16`, right?
> 
> While I acknowledge that is what the current version of the JEP directs 
> to happen in this situation, the API elements in question really are 
> present in 14 and 15 so I don't think saying they are "since 16" is 
> necessarily clearer.

The reason that JEP 12 says to have @since reflect the 
final-and-permanent release rather than a preview release is to provide 
a JEP owner with a simple rule that applies regardless of whether an API 
element evolves between preview and permanent status. Just because an 
API element exists in 14 and 15 (as preview) and 16 (as permanent) 
doesn't mean it has exactly the same semantics in 16 as in 14 or 15 -- 
previewing is the one avenue by which an element can materially change 
its behavior between 14 and 15 and 16. Also, where API elements are 
previewed over time, the choice to have some elements be @since 14 while 
others are @since 15 or @since 16 would cause confusion in future -- 
"Are the 14 and 15-era elements associated with records considered to be 
final, given that records weren't finalized until 16? Might the 14 and 
15-era elements be removed one day?" -- so I think it's best to focus 
@since consistently on the release where a feature becomes 
final-and-permanent.

Alex