Introduction tests for `@since` Tags in OpenJDK

[Nizar Benalla]

Hello OpenJDK Developers,

This note is to inform you about a new effort regarding `@since` tags in our codebase. Starting now, their values will be tested by a collection of Tier 3 tests.

Tests:
- A test will be implemented for each module.
- To run all tests before a push, use:
  ```
  make test TEST=jdk_since_checks
  ```
- To run a test for a specific module using jtreg, you can provide a directory path. For example, for the `java.base` module:
  ```
  jtreg [OPTIONS] test/jdk/tools/sincechecker/modules/java_base/CheckSince_javaBase.java
  ```

2. Performance:
- Running the test for the `java.base` module only takes 20 seconds.
- Running the test for other modules can take 10 seconds.
- Running all of the tests can take up to 5 minutes.

Context:
The `@since` information is now of increased importance due to its role in the "new API in JDK$N" pages. The accuracy of this data is crucial for developers to track new features and changes.  As a rule, every declaration should have an @since tag, except for members where it would be the same as for the enclosing class or interface. The rules for determining @since tags are detailed in this [CSR][2].

Additional Information:
- Scope: The tests currently focus on code from JDK 9 onwards.
- Preview Features: Handling of preview elements is as described in [JEP 12][3].
- Covariant Overrides: These are treated as new methods, requiring a new `@since` tag.

We will be making a few fixes to add missing @since tags in the documentation. After these fixes, this process should prevent such mistakes from happening in the future.

Thank you,
Nizar

[1]: https://docs.oracle.com/en/java/javase/22/docs/api/new-list.html
[2]: https://bugs.openjdk.org/browse/JDK-8334325
[3]: https://openjdk.org/jeps/12
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20240626/9ca27e41/attachment-0001.htm>