From f2446f2dfba1b5d0cde91dfeba043c1742a145c2 Mon Sep 17 00:00:00 2001 From: Gray Mackall <34871572+gmackall@users.noreply.github.com> Date: Wed, 20 Nov 2024 12:58:39 -0800 Subject: [PATCH] Add docs for setting up Android Studio to auto format Kotlin code (#159209) Docs to make Android Studio auto format kotlin code in a way compatible with the format check that we make in CI. Open to suggestions as to a better place to put them, but there wasn't an existing doc that seemed like an obvious fit to me. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [ ] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: Gray Mackall Co-authored-by: Reid Baker --- dev/bots/analyze.dart | 3 ++- .../Kotlin-android-studio-formatting.md | 27 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 docs/platforms/android/Kotlin-android-studio-formatting.md diff --git a/dev/bots/analyze.dart b/dev/bots/analyze.dart index 7102ecb51f..5663ac062e 100644 --- a/dev/bots/analyze.dart +++ b/dev/bots/analyze.dart @@ -2126,7 +2126,8 @@ Future lintKotlinFiles(String workingDirectory) async { 'To reproduce this lint locally:\n' '1. Identify the CIPD version tag used to resolve this particular version of ktlint (check the dependencies section of this shard in the ci.yaml). \n' '2. Download that version from https://chrome-infra-packages.appspot.com/p/flutter/ktlint/linux-amd64/+/\n' - '3. From the repository root, run `/ktlint --editorconfig=$editorConfigRelativePath --baseline=$baselineRelativePath`'; + '3. From the repository root, run `/ktlint --editorconfig=$editorConfigRelativePath --baseline=$baselineRelativePath`\n' + 'Alternatively, if you use Android Studio, follow the docs at docs/platforms/android/Kotlin-android-studio-formatting.md to enable auto formatting.'; foundError([errorMessage]); } } diff --git a/docs/platforms/android/Kotlin-android-studio-formatting.md b/docs/platforms/android/Kotlin-android-studio-formatting.md new file mode 100644 index 0000000000..c5a1117be0 --- /dev/null +++ b/docs/platforms/android/Kotlin-android-studio-formatting.md @@ -0,0 +1,27 @@ +# Setting up Kotlin formatting in Android Studio + +Kotlin code in this repository is formatted and linted with [`ktlint`](https://github.com/pinterest/ktlint). +If you +1. have submitted Kotlin code only to learn this when the analyzer check fails +2. use Android Studio + + +then there is good news! Android Studio can be configured to use `ktlint` to automatically apply formatting and highlight issues. To do this: + + +1. Install the `ktlint` extension for Android Studio + + a. On Mac, this is `Android Studio > Settings > Plugins > ` Search for `ktlint`. + +2. Set the ruleset to be the same as the version used in [`.ci.yaml`](../../../.ci.yaml) (as of writing this is 1.1.1), and the baseline to be `dev/bots/test/analyze-test-input/ktlint-baseline.xml`. + + a. Both of these options should be available under `Android Studio > Settings > Tools > ktlint`. + +3. Additionally, Kotlin code in the Flutter repository currently uses some additional rules for compatibility with older versions of Kotlin. +These rules can only be configured by an `.editorconfig` file in the directory from which Android Studio was opened. To configure these rules, create a new `.editorconfig` file in the root of your flutter repository with the following content +``` +[*.{kt,kts}] +# Disable trailing commas to allow compatibility with Kotlin versions less than 1.4. +ij_kotlin_allow_trailing_comma = false +ij_kotlin_allow_trailing_comma_on_call_site = false +```