Format Java source files automatically

CONTRIBUTING.md

@@ -155,19 +155,73 @@ For Eclipse, go to `Preferences->Java->Installed JREs` and add `-ea` to
 
 ### Java Language Formatting Guidelines
 
+Java files in the Elasticsearch codebase are formatted with
+[google-java-format](https://github.com/google/google-java-format), which
+enforces the [Google Java
+Style](https://google.github.io/styleguide/javaguide.html). The formatting
+check can be run explicitly with:
+
+    ./gradlew spotlessJavaCheck
+
+The code can be formatted with:
+
+    ./gradlew spotlessApply
+
+These tasks can also be run for specific subprojects, e.g.
+
+    ./gradlew server:spotlessJavaCheck
+
+Code is formatted with the `--aosp` option (Android Open Source Project),
+which indents with 4 spaces instead of 2. There are no other formatting
+options available by design.
+
 Please follow these formatting guidelines:
 
 * Java indent is 4 spaces
-* Line width is 140 characters
-* Lines of code surrounded by `// tag` and `// end` comments are included in the
-documentation and should only be 76 characters wide not counting
-leading indentation
-* The rest is left to Java coding standards
-* Disable “auto-format on save” to prevent unnecessary format changes. This makes reviews much harder as it generates unnecessary formatting changes. If your IDE supports formatting only modified chunks that is fine to do.
-* Wildcard imports (`import foo.bar.baz.*`) are forbidden and will cause the build to fail. This can be done automatically by your IDE:
- * Eclipse: `Preferences->Java->Code Style->Organize Imports`. There are two boxes labeled "`Number of (static )? imports needed for .*`". Set their values to 99999 or some other absurdly high value.
- * IntelliJ: `Preferences/Settings->Editor->Code Style->Java->Imports`. There are two configuration options: `Class count to use import with '*'` and `Names count to use static import with '*'`. Set their values to 99999 or some other absurdly high value.
-* Don't worry too much about import order. Try not to change it but don't worry about fighting your IDE to stop it from doing so.
+* Line width is 100 characters
+* Lines of code surrounded by `// tag` and `// end` comments are included
+  in the documentation and should only be 76 characters wide not counting
+  leading indentation
+* Wildcard imports (`import foo.bar.baz.*`) are forbidden and will cause
+  the build to fail. This can be done automatically by your IDE:
+   * Eclipse: `Preferences->Java->Code Style->Organize Imports`. There are
+     two boxes labeled "`Number of (static )? imports needed for .*`". Set
+     their values to 99999 or some other absurdly high value.
+   * IntelliJ: `Preferences/Settings->Editor->Code Style->Java->Imports`.
+     There are two configuration options: `Class count to use import with
+     '*'` and `Names count to use static import with '*'`. Set their values
+     to 99999 or some other absurdly high value.
+
+#### Editor / IDE Support
+
+See the `google-java-format` repository for details on installing the
+[plugins for Jetbrains IDEs] and [Eclipse plugins].
+
+For editors that support formatting via a CLI command, see the
+[google-java-format CLI instructions].
+
+#### Formatting failures
+
+Sometimes Spotless will report a "misbehaving rule which can't make up its
+mind" and will recommend enabling the `paddedCell()` setting. If you
+enabled this settings and run the format check again,
+Spotless will write files to
+`$PROJECT/build/spotless-diagnose-java/` to aid diagnosis. It writes
+different copies of formatted files, so that you can see how they differ
+and infer what is the problem. Ther are two common problems:
+
+   1. Single-line comments at the end of a line of code can be wrapped onto
+      multiple lines during one formatting interation, and then change
+      indentation in another iteration. The solution is to identify the
+      comment and move it so that it is consistently formatted.
+      Multiline-style comments are not affected.
+   2. Sometimes `<p>` tags are inserted within `<code>` tags in JavaDoc.
+      The solution is to wrap with `<pre>` tags. See:
+
+      https://github.com/google/google-java-format/issues/254
+
+The `paddedCell() option is disabled for normal operation in order to
+detect any misbehaviour.
 
 ### License Headers
 
@@ -391,3 +445,6 @@ repeating in this section because it has come up in this context.
 [eclipse]: http://www.eclipse.org/community/eclipse_newsletter/2017/june/
 [intellij]: https://blog.jetbrains.com/idea/2017/07/intellij-idea-2017-2-is-here-smart-sleek-and-snappy/
 [shadow-plugin]: https://github.com/johnrengelman/shadow
+[plugins for Jetbrains IDEs]: https://github.com/google/google-java-format#intellij-android-studio-and-other-jetbrains-ides
+[Eclipse plugins]: https://github.com/google/google-java-format#eclipse
+[google-java-format CLI instructions]: https://github.com/google/google-java-format#from-the-command-line

build.gradle

@@ -35,6 +35,7 @@ plugins {
     id 'com.gradle.build-scan' version '2.4'
     id 'lifecycle-base'
     id 'elasticsearch.global-build-info'
+    id "com.diffplug.gradle.spotless" version "3.24.2" apply false
 }
 
 apply plugin: 'nebula.info-scm'
@@ -98,6 +99,30 @@ subprojects {
   plugins.withType(BuildPlugin).whenPluginAdded {
     project.licenseFile = project.rootProject.file('licenses/APACHE-LICENSE-2.0.txt')
     project.noticeFile = project.rootProject.file('NOTICE.txt')
+
+    // Projects that should be formatted with Spotless are listed here, by
+    // project path. Once the number of formatted projects is greater than
+    // the number of unformatted projects, this can be switched to an
+    // exclude list, and eventualy removed completely.
+    def projectPathsToFormat = [
+      ':build-tools'
+    ]
+
+    if (projectPathsToFormat.contains(project.path)) {
+      project.apply plugin: "com.diffplug.gradle.spotless"
+
+      spotless {
+        java {
+          // Use Android Open Source Project settings (i.e. 4 space indents)
+          googleJavaFormat().aosp()
+
+          // See CONTRIBUTING.md for details of when to enabled this.
+          // paddedCell()
+        }
+      }
+
+      precommit.dependsOn 'spotlessJavaCheck'
+    }
   }
 }
 

buildSrc/build.gradle

@@ -112,7 +112,7 @@ dependencies {
   compile 'com.netflix.nebula:gradle-extra-configurations-plugin:3.0.3'
   compile 'com.netflix.nebula:nebula-publishing-plugin:4.4.4'
   compile 'com.netflix.nebula:gradle-info-plugin:3.0.3'
-  compile 'org.eclipse.jgit:org.eclipse.jgit:3.2.0.201312181205-r'
+  compile 'org.eclipse.jgit:org.eclipse.jgit:5.5.0.201909110433-r'
   compile 'com.perforce:p4java:2012.3.551082' // THIS IS SUPPOSED TO BE OPTIONAL IN THE FUTURE....
   compile 'org.apache.rat:apache-rat:0.11'
   compile "org.elasticsearch:jna:4.5.1"