Document the procedure of upgrading to the new Kotlin version #4557
Conversation
| ``` | ||
|
|
||
| 1. In `gradle.properties`, | ||
| set `kotlin_version` to the `<version>`. |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
| 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. | ||
|
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Sounds good! Though, avoid "TODO", since TODOs are reported by Idea and they are not actionable if they are blocked by a version.
There was a problem hiding this comment.
Also: "remove after", "fix in", etc.
There was a problem hiding this comment.
Also, we usually say "after old version", not "after new version", so we need to search for the old version as well
There was a problem hiding this comment.
Created an issue to cleanup all those workarounds.
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. |
There was a problem hiding this comment.
Shall we have a separate mini page / section about building the project locally?
-
I had to install tvOS and other simulators through xcode, and it was not a trivial "next, next, ok". (refer to our DMs)
-
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.
There was a problem hiding this comment.
- 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.
- In that case, you didn't run the correct code.
./integration-testing/gradlew clean checkmeans "run the taskscleanandcheckin the project from the current directory, using the Gradle version from theintegration-testingdirectory".
There was a problem hiding this comment.
- 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
- Our tests don't do anything special in that regard, we are simply listing
tvOSas one of our targets, and the Kotlin Gradle Plugin does the rest.
There was a problem hiding this comment.
It did require me to install the emulator, though.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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".
There was a problem hiding this comment.
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.
Fixes #4521