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

[Joe Darcy]

On 9/30/2020 3:57 PM, Alex Buckley wrote:
> 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. 


Conversely, the fact that an API element is preview on one release and 
non-preview in a subsequent one does not necessarily imply the spec has 
changed. (Although it might have changed, of course.)

Non-preview methods don't necessarily have *exactly* the same semantics 
between releases either, subject to our general API evolution policies.


> 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.
>
Another kind of consistency would be "use the @since tag for the release 
the API element was first added." For readers, it would be a simple rule 
that non-preview and not-deprecated-for-removal API elements can be 
assumed to be present in the next release.

-Joe