[crac] RFR: 8364554: [CRaC] Improve CRaC VM options' docs [v4]

[Timofei Pushkin]

On Fri, 8 Aug 2025 16:11:40 GMT, Radim Vansa <rvansa at openjdk.org> wrote:

>> Ended up expiring everything since 26: the options added to special in this PR are diagnostic/experimental and not widely used, so this is in accordance with OpenJDK's recommendations.
>
> Expiration by 26 is probably fine, but it seems that you're obsoleting retroactively? There is no 24-based version that would obsolete those, this will be ~25 and you're obsoleting on the spot. Except for `CRaCDoThrowCheckpointException` I would make these defunct (through expiration) only in 26.

Oh, I really did not intend to do that. I was fighting version correctness asserts and misread the guidelines in `arguments.cpp`.

The guidelines state: "To change the name of an option, use the alias table as well as a 2-step model adding major release numbers to the deprecate and expire columns", but this seems to not be possible because asserts mandate that:
- it is not allowed to only fill deprecate and expire columns, obsolete must also be filled: "<flag> must be explicitly obsoleted before expired";
- it is not allowed to set obsolete and expire columns to the same version, expire must be strictly greater: "<flag> must be obsoleted before expired".

So only a 3-step model is possible. Since we do not want to obsolete on the spot for our aliases we can only either:
- If using only major versions, obsolete in 26 and expire in 27 (for LTS releases: April and October 2026)
- If using minor versions too, obsolete in 26 and expire in 26.0.2 (for LTS releases: April and July 2026)
   - We do not want to obsolete before 26 because that would be less than a year since the deprecation of frequently-used aliases
   - To correspond to LTS versions, we cannot obsolete in 26 and expire in 26.0.1 because in LTS that would be the same April 2026 release and we'll get assert failures because obsolete == expire

I do not have a preference: the first one looks cleaner, the second one makes the aliases expire sooner. Went with the first one just to choose something.

For `CRTrace` and `CRaCDoThrowCheckpointException` it is possible to expire in 26 so I did that.

-------------

PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2263792541