fixup! Add AGENTS.md file.
diff --git a/libraries/stdlib/AGENTS.md b/libraries/stdlib/AGENTS.md index bc02170..7d92a9e 100644 --- a/libraries/stdlib/AGENTS.md +++ b/libraries/stdlib/AGENTS.md
@@ -7,10 +7,12 @@ #### Building and Testing Native Standard Library By default, Kotlin/Native compilation is disabled, and corresponding tests and binary compatibility checks are not executed. -To enable it, all Gradle commands should be executed with `-Pkotlin.native.enabled=true` argument appended. +All Gradle commands must be executed with `-Pkotlin.native.enabled=true` argument appended to enable it. #### Standard Library Source Generation +**MANDATORY for AI Agents:** Before editing any file, you MUST check if it contains "Auto-generated" or "Generated by" in its header. Such files MUST NOT be edited manually. + Some standard library sources are generated from [templates](../tools/kotlin-stdlib-gen/src/templates). Such source files have a comment explicitly mentioning that, and their names are prefixed with an underscore (e.g., `_Collections.kt`). Do not edit generated sources manually. @@ -22,14 +24,32 @@ Check [ReadMe](./ReadMe.md) for more details. +There are also builtin types generated using a separate generator task. +Builtin generators are located in [generators/builtins](../../generators/builtins) directory. +Source files generated by them have a comment starting with `Generated by org.jetbrains.kotlin.generators.builtins`. +If such a file needs to be modified, update the corresponding generator instead and then run the following Gradle task: + +``` +./gradlew generateBuiltins +``` + #### Standard Library Change Checklist -- Public API should be documented and provide samples. +- Public API must be documented and provide samples. - If possible, samples should be implemented in the [samples](samples) directory and referenced from KDoc using the `@sample` tag. - If it is not possible (for example, if a sample illustrates a code that should not compile or could not be executed), include a sample as an inline code snippet in KDoc. -- Every functional change should have corresponding tests. -- The project should be successfully compiled and tests should pass. -- Changes should not break binary compatibility, unless it is a deliberate breaking change. + - **MANDATORY for AI Agents:** Do not assume samples are optional if a neighboring API does not provide it. + - When updating documentation corresponding to expect/actual declarations, ensure that all other expect/actual declarations are also updated, unless the change is target-specific. +- Every functional change must have corresponding tests. +- The project must successfully compile for ALL targets and unit tests must pass. + - **MANDATORY for AI Agents:** Do not assume tests pass if you only run a subset. Run the full suite or target-specific tasks. + - **MANDATORY for AI Agents:** You MUST include Kotlin/Native in your verification. Since it is disabled by default, append `-Pkotlin.native.enabled=true` to all Gradle commands used for testing or binary compatibility validation. +- Binary compatibility must be validated. + - Changes should not break binary compatibility, unless it is a deliberate breaking change. + - **MANDATORY for AI Agents:** You MUST update dump files if your change adds or modifies public API. See "Binary Compatibility Requirements" below. - A newly added API should be annotated with `@SinceKotlin` with a Kotlin version as a parameter. Usually, the value of `kotlinLanguageVersion` property from [gradle.properties](../../gradle.properties) should be used. + - In rare cases, the standard library's API version may not be updated yet (e.g., if `kotlinLanguageVersion` is 2.4 but stdlib API version is still 2.3). + - In this case, compilation fails with errors like `The version is greater than the specified API version`. + - If such error happened, comment the added `@SinceKotlin` annotation and add a `// TODO` comment to uncomment it later. **Do not skip this step.** #### Running Tests After Changes - After changing stdlib sources or tests, run the libraries tests. @@ -59,10 +79,11 @@ - For JVM, dump files are located in [binary-compatibility-validator/reference-public-api](../tools/binary-compatibility-validator/reference-public-api) - For all other targets, dumps files are located in [binary-compatibility-validator/klib-public-api](../tools/binary-compatibility-validator/klib-public-api) + - **MANDATORY for AI Agents:** When updating or validating dump files, always use `-Pkotlin.native.enabled=true` to ensure Klib dumps for Native targets are also processed. - **CRITICAL: Never edit dump files manually.** -- Dump files could be only updated by running the following Gradle command: +- Dump files could be updated only by running the following Gradle command: ``` ./gradlew :tools:binary-compatibility-validator:cleanTest :tools:binary-compatibility-validator:test -Poverwrite.output=true @@ -70,7 +91,7 @@ - If the updated dump includes new lines, the change is considered a binary compatible. - If some lines were completely removed, the change is considered a binary incompatible. -- The change, until otherwise is required, should preserve binary compatibility. +- The change, until otherwise is required, must preserve binary compatibility. - To double-check that dump files reflect all changes, run the following Gradle command: ```