Kotlin / Kotlin/api-guidelines
Add a section on the importance of apiVersion, Xjdk-release, and java'c release
- Dominant language
- No language data
- Stars
- 154
- Forks
- 25
- Avg merge
- 19d 1h
- Merged PRs (30d)
- 1
Description
Currently, the guide does not clarify why it is important for the library authors to target older Kotlin and Java releases, so they get confused.
I suggest there should be a section that explains the following:
* `apiVersion`: clarify why it is important, and suggest the strategy for the library authors
* `languageVersion`: clarify why it is important, and suggest the strategy for the library authors
* `coreLibrariesVersion`: clarify why it is important, and suggest the strategy for the library authors
* `KotlinJvmCompile.jvmTarget`: clarify why it is important, and clarify why bytecode version is not enough
* `KotlinJvmCompile.Xjdk-release`: clarify why it is important
* `JavaCompile.release`: clarify why it is [important](https://www.morling.dev/blog/bytebuffer-and-the-dreaded-nosuchmethoderror/)
* `java.sourceCompatibility`, `java.targetCompatibility`: clarify they should never be used with javac 11+ (they do not protect from `NoSuchMethodError`)
See also:
* https://kotlinlang.org/docs/api-guidelines-introduction.html
* https://speakerdeck.com/martinbonnin/metadataquoi
* https://www.morling.dev/blog/bytebuffer-and-the-dreaded-nosuchmethoderror
Contributor guide
Research direction
Start by locating the guide section for library authors and review the linked Kotlin API guidelines, metadata presentation, and NoSuchMethodError article. Add a section explaining the listed version and release settings, their compatibility implications, and why source or target compatibility alone is insufficient; done means each requested setting is addressed clearly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, kotlin
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100