jspecify / jspecify/jdk

Remove more annotations from non-visible APIs

Open
#101 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
7
Forks
3
Avg merge
15h 17m
Merged PRs (30d)
8

Description

  • Annotating them is more work, so we don't want to encourage more of that.
  • We already annotate them only incompletely, so we don't want the presence of annotations to suggest that we have been being complete.
  • Not only does annotating private APIs require more work up front, but even existing annotations have a cost because they complicate merges, as noted in https://github.com/jspecify/jdk/commit/cbe846fe600ad40444c4be775c8992d5f7ad7bfd.
  • Even if we annotate private APIs correctly today, we can't rely on them to keep their current behavior even as reliably as public APIs do (which, as we know, is not 100% but should at least be highly reliable—and noteworthy when changes do occur).
    • [edit: I think this was a reference to behavior changes in System.console. However, I think we eventually concluded that System.console had technically remained @Nullable, even though the cases in which users could see null became much more restricted. We could also have the philosophical discussion about whether @Nullable can ever be truly "wrong" (as opposed to just a very imprecise and bad idea) in the return type of a static method :)]
  • I had forgotten about the crash we had from a change to an internal API back in https://github.com/jspecify/jdk/pull/56.

[edit: done some in 300a39f]

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing annotations on non-visible APIs and the partial removal noted in commit 300a39f. Read the linked historical commit and JDK pull request #56 for context, and inspect the System.console discussion before determining what remains. Done means the intended additional private or non-visible annotations are removed without expanding annotation coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.