Deprecate shorcuts for import-ordering (pinterest#1018)

* Deprecate shorcuts for import-ordering

* Update CHANGELOG.md

Author: romtsn

.editorconfig

@@ -14,7 +14,7 @@ insert_final_newline = true
 indent_size = 4
 
 [*.{kt,kts}]
-kotlin_imports_layout=ascii
+ij_kotlin_imports_layout=*
 
 [{Makefile,*.go}]
 indent_style = tab

CHANGELOG.md

@@ -10,11 +10,16 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Empty line before primary constructor is not reported and formatted-out ([#1004](https://github.com/pinterest/ktlint/issues/1004))
 - Fix '.editorconfig' generation for "import-ordering" rule ([#1011](https://github.com/pinterest/ktlint/issues/1004))
 - Fix "filename" rule will not work when '.editorconfig' file is not found ([#997](https://github.com/pinterest/ktlint/issues/1004))
+- EditorConfig generation for `import-ordering` ([#1011](https://github.com/pinterest/ktlint/pull/1011))
 
 ### Changed
 - Update Gradle shadow plugin to `6.1.0` version
 - Align with Kotlin plugin on how alias pattern is represented for imports layout rule ([#753](https://github.com/pinterest/ktlint/issues/753))
 - Align with Kotlin plugin on how subpackages are represented ([#753](https://github.com/pinterest/ktlint/issues/753))
+- Deprecated custom `kotlin_imports_layout` EditorConfig property. Please use `ij_kotlin_imports_layout` to ensure 
+  that the Kotlin IDE plugin and ktlint use same imports layout ([#753](https://github.com/pinterest/ktlint/issues/753))
+- Deprecated `idea` and `ascii` shortcuts as the `ij_kotlin_imports_layout` property does not support those. 
+  Please check README on how to achieve those with patterns ([#753](https://github.com/pinterest/ktlint/issues/753))
 
 ### Removed
 

README.md

@@ -90,20 +90,15 @@ max_line_length=off
 # by the ruleset identifier.
 disabled_rules=no-wildcard-imports,experimental:annotation,my-custom-ruleset:my-custom-rule
 
-# Defines the imports layout. There are predefined layouts like "ascii" or "idea", as well as a custom layout.
-# The predefined layouts are temporary and will be deprecated in the future, once Kotlin plugin supports EditorConfig property for imports layout.
-# The custom layout can be composed by the following symbols:
+# Defines the imports layout. The layout can be composed by the following symbols:
 # "*" - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.
 # "|" - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.
 # "^" - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.
 # import paths - these can be full paths, e.g. "java.util.List.*" as well as wildcard paths, e.g. "kotlin.**"
-# Examples:
-kotlin_imports_layout=ascii # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
-kotlin_imports_layout=idea # default IntelliJ IDEA style, same as "ascii", but with "java", "javax", "kotlin" and alias imports in the end of the imports list
-kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,**,^ # custom imports layout
-# Alternatively ij_kotlin_imports_layout name can be used, in order to set an imports layout for both ktlint and IDEA via a single property
-# Note: this is not yet implemented on IDEA side, so it only takes effect for ktlint
-ij_kotlin_imports_layout=*
+# Examples (we use ij_kotlin_imports_layout to set an imports layout for both ktlint and IDEA via a single property):
+ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
+ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
+ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
 ```
 
 ### Overriding Editorconfig properties for specific directories

ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/ImportOrderingRule.kt

@@ -19,9 +19,9 @@ import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.PsiWhiteSpaceImpl
 import org.jetbrains.kotlin.psi.KtImportDirective
 
 /**
- * Import ordering is configured via EditorConfig's custom property `kotlin_imports_layout`. Supported values:
- * * "idea" - default IntelliJ IDEA's order, see [IDEA_PATTERN]
- * * "ascii" - alphabetical order as recommended in Android's Kotlin style guide, see [ASCII_PATTERN]
+ * Import ordering is configured via EditorConfig's property `ij_kotlin_imports_layout`, so the Kotlin IDE plugin also recongizes it. Supported values:
+ * * "*,java.**,javax.**,kotlin.**,^" - default IntelliJ IDEA's order, see [IDEA_PATTERN]
+ * * "*" - alphabetical order as recommended in Android's Kotlin style guide, see [ASCII_PATTERN]
  * * custom - defined by the following set of tokens. Tokens can be combined together in a group, groups/tokens must be comma separated:
  *  * "*" - wildcard symbol, can be used as follows:
  *      1. Single, meaning matching any import (<all other imports> in IDEA)
@@ -33,7 +33,7 @@ import org.jetbrains.kotlin.psi.KtImportDirective
  *      2. Alone, meaning matching any alias import - "^" (<all other alias imports> in IDEA)
  *  * import paths - these can be full paths, e.g. "java.util.List.*" as well as wildcard paths meaning "with subpackages", e.g. "kotlin.**"
  *
- * In case the custom property is not provided, the rule defaults to "ascii" style in case of "android" flag supplied, or to "idea" otherwise.
+ * In case the custom property is not provided, the rule defaults to alphabetical order in case of "android" flag supplied, or to idea otherwise.
  */
 @OptIn(FeatureInAlphaState::class)
 public class ImportOrderingRule :
@@ -84,14 +84,26 @@ public class ImportOrderingRule :
                         value,
                         "Import layout must contain at least one entry of a wildcard symbol (*)"
                     )
-                    value == "idea" -> PropertyType.PropertyValue.valid(
-                        value,
-                        IDEA_PATTERN
-                    )
-                    value == "ascii" -> PropertyType.PropertyValue.valid(
-                        value,
-                        ASCII_PATTERN
-                    )
+                    value == "idea" -> {
+                        println(
+                            "[WARNING] `idea` is deprecated! Please use `*,java.**,javax.**,kotlin.**,^` instead" +
+                                " to ensure that the Kotlin IDE plugin recognizes the value"
+                        )
+                        PropertyType.PropertyValue.valid(
+                            value,
+                            IDEA_PATTERN
+                        )
+                    }
+                    value == "ascii" -> {
+                        println(
+                            "[WARNING] `ascii` is deprecated! Please use `*` instead" +
+                                " to ensure that the Kotlin IDE plugin recognizes the value"
+                        )
+                        PropertyType.PropertyValue.valid(
+                            value,
+                            ASCII_PATTERN
+                        )
+                    }
                     else -> try {
                         PropertyType.PropertyValue.valid(
                             value,
@@ -106,6 +118,7 @@ public class ImportOrderingRule :
                 }
             }
 
+        @Deprecated("This custom property is deprecated in favor of IDEA's default ideaImportsLayoutProperty")
         internal val ktlintCustomImportsLayoutProperty =
             UsesEditorConfigProperties.EditorConfigProperty<List<PatternEntry>>(
                 type = PropertyType(
@@ -219,6 +232,10 @@ public class ImportOrderingRule :
     private fun EditorConfigProperties.resolveImportsLayout(
         android: Boolean
     ): List<PatternEntry> = if (containsKey(KTLINT_CUSTOM_IMPORTS_LAYOUT_PROPERTY_NAME)) {
+        println(
+            "[WARNING] `kotlin_imports_layout` is deprecated! Please use `ij_kotlin_imports_layout` to ensure" +
+                " that the Kotlin IDE plugin and ktlint use same imports layout"
+        )
         getEditorConfigValue(ktlintCustomImportsLayoutProperty, android)
     } else {
         getEditorConfigValue(ideaImportsLayoutProperty, android)

ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/importordering/ImportOrderingRuleAsciiTest.kt

@@ -297,7 +297,7 @@ class ImportOrderingRuleAsciiTest {
     private fun writeAsciiImportsOrderingConfig() = editorConfigTestRule
         .writeToEditorConfig(
             mapOf(
-                ImportOrderingRule.ideaImportsLayoutProperty.type to "ascii"
+                ImportOrderingRule.ideaImportsLayoutProperty.type to "*"
             )
         )
         .absolutePath

ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/importordering/ImportOrderingRuleIdeaTest.kt

@@ -353,7 +353,7 @@ class ImportOrderingRuleIdeaTest {
     private fun writeIdeaImportsOrderingConfig() = editorConfigTestRule
         .writeToEditorConfig(
             mapOf(
-                ImportOrderingRule.ideaImportsLayoutProperty.type to "idea"
+                ImportOrderingRule.ideaImportsLayoutProperty.type to "*,java.**,javax.**,kotlin.**,^"
             )
         )
         .absolutePath