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

[Alex Buckley]

On 9/30/2020 4:48 PM, Joe Darcy wrote:> 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.

I recognize that a permanent API element may have its behavior changed 
in some situations, and we would leave @since alone in that context. For 
example, a method flagged with @since 8 might have been extended in 9 to 
handle modules, and we would not dream of saying @since 9.

However, a preview API element has an order of magnitude more freedom to 
change than a permanent API element. This means that the element 
previewing in 15 might have the same name and signature as the element 
which previewed in 14, but with novel behavior in some _or even all_ 
situations ... if that happens, then it would be misleading to suggest 
that the novel aspect of the element's spec has been present since 14 
just because the element itself has been present since 14. The element 
in 15 is not really the same element as in 14, and the element in 16 
might not be the same element as in 15. Updating @since to 16 when the 
element becomes permanent wipes the slate clean (the preview behavior no 
longer matters) and lets the element join the club of "non-preview and 
not-deprecated-for-removal API elements" which "can be assumed to be 
present in the next release."

Alex