Remove more annotations from non-visible APIs
Open
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 thatSystem.consolehad technically remained@Nullable, even though the cases in which users could seenullbecame much more restricted. We could also have the philosophical discussion about whether@Nullablecan ever be truly "wrong" (as opposed to just a very imprecise and bad idea) in the return type of a static method :)]
- [edit: I think this was a reference to behavior changes in
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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