Skip to content

Document the procedure of upgrading to the new Kotlin version #4557

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 27, 2025
Merged

Document the procedure of upgrading to the new Kotlin version #4557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions KOTLIN_UPGRADE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Checklist for upgrading to the new Kotlin version

1. Create a new branch based off `develop`:
```sh
git fetch
git checkout -b kotlin-<version> origin/develop
```

1. In `gradle.properties`,
set `kotlin_version` to the `<version>`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFU has a script automating the version-replace step (but its about AFU-version, not a Kotlin version it depends on), you can reuse it, if you see a value in that: https://github.com/Kotlin/kotlinx-atomicfu/blob/master/bump-version.sh

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have our own, improved version of that script: https://github.com/Kotlin/kotlinx.coroutines/blob/master/bump-version.sh If you want, I can make a PR to atomicfu and port the improvements.


2. Likewise, set `kotlin_version` in `integration-testing/gradle.properties`.

3. In `README.md`,
replace the occurrences of the old version with the `<version>`.
These are:
- A badge at the top of the file.
- The Kotlin version corresponding to the latest release,
mentioned in the first paragraph.
- Maven and Gradle configuration blocks.

4. In `README.md`, find the link to https://pl.kotl.in/ and open it.
Set the compiler version of Kotlin Playground to the same major version as `<version>`,
click "Copy link", and replace the original link in `README.md` with the new one.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add: Search for <version> in the whole project for comments like // fix in Kotlin 2.x.x and either fix, if minor, or create an issue.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#4485 (review)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea is good. It would bring the most utility if we adopted a machine-searchable unified comment format for this, like // TODO: revisit after $dependency $version, where $dependency is one of the tokens followed by _version in https://github.com/Kotlin/kotlinx.coroutines/blob/8c27d51025d56a7b8de8eec2fb234b0094ce84f1/gradle.properties. For Kotlin, it would be almost like the comment you propose, just a bit more general, not limited to bug fixes. What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good! Though, avoid "TODO", since TODOs are reported by Idea and they are not actionable if they are blocked by a version.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also: "remove after", "fix in", etc.

https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/common/src/TestBuilders.kt#L608

https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/common/src/internal/LocalAtomics.common.kt#L9

https://github.com/Kotlin/kotlinx.coroutines/blob/master/integration-testing/src/mavenTest/kotlin/MavenPublicationAtomicfuValidator.kt#L40

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, we usually say "after old version", not "after new version", so we need to search for the old version as well

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"fixed", "workaround"

Copy link
Contributor

@murfel murfel Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created an issue to cleanup all those workarounds.

#4560

Hopefully we will remember to comment them correctly and search for them after upgrading.

5. Perform a full build: `gradle clean check publishToMavenLocal`,
followed by `gradle clean check` in the `integration-testing` directory.
Fix any issues that arise.
Comment on lines +26 to +28
Copy link
Contributor

@murfel murfel Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall we have a separate mini page / section about building the project locally?

  1. I had to install tvOS and other simulators through xcode, and it was not a trivial "next, next, ok". (refer to our DMs)

  2. I had to run it like this

./integration-testing/gradlew clean check

Rather than cd integration-testing, ./gradlew clean check

I don't know if this is obvious gradle 101, but since we are documenting everything anyway, why not.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. I haven't had to do that for a long time, but if installing emulators is non-trivial the right place for mentioning this is https://kotlinlang.org/docs/native-get-started.html, I believe. Right now, it just says

If you use a Mac and want to create and run applications for macOS or other Apple targets, you also need to install Xcode Command Line Tools, launch it, and accept the license terms first.

  1. In that case, you didn't run the correct code. ./integration-testing/gradlew clean check means "run the tasks clean and check in the project from the current directory, using the Gradle version from the integration-testing directory".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. ack

Copy link
Contributor

@murfel murfel Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. It's not about installing xcode and related tooling, it's about installing the environment where our tests are run. You can use Kotlin/Native and not use the tvOS emulator.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about we keep it as is right now, and I'll do a proper build page later?

This is mostly a mac issue, and I assume you don't really use mac. I was going to reinstall my mac anyway, I'll document everything I need to install to build kotlinx.coroutines locally on mac.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Our tests don't do anything special in that regard, we are simply listing tvOS as one of our targets, and the Kotlin Gradle Plugin does the rest.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It did require me to install the emulator, though.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I understand that, my point is, everyone attempting to build any Kotlin library that has tvOS as a target will also have to install the emulator, this is not unique to kotlinx.coroutines, so we'd like everyone to benefit from this being documented, not just us.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a user is using tvOS with Kotlin/Native, they will know that they should install the emulator.

The problem here is that a user might want to run the test suit, which runs tests for everything, and it is unique to our library (and other first-party kotlin libraries).

I'm happy to do a build page for all our first-party libraries, but I disagree that it should belong to the "Get started with Kotlin/Native".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem here is that a user might want to run the test suit, which runs tests for everything, and it is unique to our library (and other first-party kotlin libraries).

That's the case for any KMP library, and libraries supported by JetBrains are not special in that regard. Thus setting up an environment to build and execute multiplatform code is a part of Kotlin/Native setup and the proper place to provide guidance on setting it up are K/N docs.

If build fails due to missing emulator, but it is not clear from provided diagnostic messages, then build tools should be improved to make it clear for a user.


6. Commit and push all changes to GitHub:
```sh
git commit -am 'Upgrade to Kotlin <version>'
git push -u origin kotlin-<version>
```

7. Wait for the TeamCity continuous integration builds to finish.

8. Open a new pull request, receive approval, and merge.
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ This is a companion version for the Kotlin `2.2.20` release.
```kotlin
suspend fun main() = coroutineScope {
launch {
delay(1000)
delay(1.seconds)
println("Kotlin Coroutines World!")
}
println("Hello")
}
```

> Play with coroutines online [here](https://pl.kotl.in/Wf3HxgZvx)
> Play with coroutines online [here](https://pl.kotl.in/xdbDf0NNk)

## Modules

Expand Down