Kotlin / Kotlin/api-guidelines

Add a section on the importance of apiVersion, Xjdk-release, and java'c release

Open
#44 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.