| AndroidX Core Team | 80b2295 | 2025-04-25 09:38:50 -0700 | [diff] [blame] | 1 | # KGP Integration |
| 2 | |
| 3 | go/androidx-kgp-integration |
| 4 | |
| 5 | <!--* |
| 6 | # Document freshness: For more information, see go/fresh-source. |
| 7 | freshness: { owner: 'aurimas', owner: 'juliamcclellan', owner: 'fsladkey' reviewed: '2025-04-24' } |
| 8 | *--> |
| 9 | |
| 10 | [TOC] |
| 11 | |
| 12 | To catch Kotlin upgrade issues before upgrade time, AndroidX team has set up an |
| 13 | integration test with the latest version of Kotlin gradle plugin available on |
| 14 | the |
| 15 | [JetBrains dev repository](https://packages.jetbrains.team/maven/p/kt/dev/org/jetbrains/kotlin/kotlin-gradle-plugin/maven-metadata.xml). |
| 16 | |
| 17 | The integration tests run on GitHub and can be found |
| 18 | [here](https://github.com/androidx/androidx/actions/workflows/kgp-nightly-integration.yml). |
| 19 | Currently they build the `collection` project. |
| 20 | |
| 21 | Because some code cannot be made compatible with both the current version and |
| 22 | the latest version, a |
| 23 | [patch file](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:.github/integration-patches/kgp-nightly.patch) |
| 24 | is applied before the test runs. |
| 25 | |
| 26 | ## Fixing failing integration tests |
| 27 | |
| 28 | The test can fail for a few reasons. |
| 29 | |
| 30 | #### Changes in KGP which can be made compatible in androidx-main |
| 31 | |
| 32 | Simply make the change (e.g. suppression) in aosp and merge the change. |
| 33 | |
| 34 | #### Changes in KGP which cannot be made in androidx-main, and/or failure to apply changes |
| 35 | |
| 36 | * Upgrade to the latest Kotlin version used by the integration test with |
| 37 | `./development/update_kotlin.sh <KOTLIN_VERSION>` |
| 38 | * If there is an existing patch file, apply it with `git apply |
| 39 | .github/integration-patches/kgp-nightly.patch` |
| 40 | * If the patch file cannot be applied due to merge conflicts, see the |
| 41 | instructions |
| 42 | [here](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:.github/integration-patches/). |
| 43 | * Make any necessary changes |
| 44 | * Ensure `collection` builds locally |
| 45 | * Run the following (or something similar) to update the patch file |
| 46 | |
| 47 | ``` |
| 48 | # copy new patch file to a temporary file or directly to clipboard |
| 49 | git diff HEAD~2 -- :^.github :^development :^gradle/libs.versions.toml > tmp.patch |
| 50 | # start a new branch and replace the contents of the patch file |
| 51 | repo start update-patch-file |
| 52 | cat tmp.patch > .github/integration-patches/kgp-nightly.patch |
| 53 | ``` |
| 54 | |
| 55 | * Commit the changes to the new branch |
| 56 | * Validate that patch applies by running `git apply --stat |
| 57 | .github/integration-patches/kgp-nightly.patch` |
| 58 | * Upload and merge the change |
| 59 | * Trigger the |
| 60 | [integration branch](https://github.com/androidx/androidx/actions/workflows/kgp-nightly-integration.yml) |
| 61 | to validate the changes |
| 62 | |
| 63 | #### Bugs in KGP |
| 64 | |
| 65 | If a change appears to be an unintentional breakage by KGP, the failure should |
| 66 | be reported to Jetbrains. If possible, try to work around the failure with one |
| 67 | of the above methods so that the integration test can continue catching |
| 68 | additional regressions. |
