Rationalize and apply consistent project settings

.gitignore

@@ -5,3 +5,7 @@ target/
 generated-sources/
 .metadata/
 **/.*.swp
+eclipse/.settings
+plugins/.settings
+features/.settings
+third_party/.settings

README.md

@@ -20,16 +20,25 @@ Maven for building Eclipse bundles and features.
   this somewhere on your file system.
 
 1. The [Eclipse IDE](https://www.eclipse.org/downloads/eclipse-packages/).
-  It's easiest to use the _Eclipse IDE for Java EE Developers_ package. You can use
-  Eclipse 4.6 (Neon) or 4.7 (Oxygen) as we define a target platform to build and run against.
+  It's easiest to use the _Eclipse IDE for Java EE Developers_ package. You must use
+  Eclipse 4.7 (Oxygen) or later.  We use _target platforms_ to support building
+  for earlier versions of Eclipse.  You also need the following:
 
-  1. The [m2eclipse plugin](http://www.eclipse.org/m2e/) (also called m2e) is
-     required to import the projects into Eclipse.  m2eclipse is included in
+  1. The [M2Eclipse plugin](http://www.eclipse.org/m2e/) (also called m2e) is
+     required to import the projects into Eclipse.  M2Eclipse is included in
      [several packages](https://www.eclipse.org/downloads/compare.php?release=neon),
      such as the _Eclipse IDE for Java EE Developers_ package.
 
   2. The [m2e connector for maven-dependency-plugin](https://github.com/ianbrandt/m2e-maven-dependency-plugin)
      should be installed from `http://ianbrandt.github.io/m2e-maven-dependency-plugin/`.
+     This connector should be prompted for by M2Eclipse.  If not, use
+     _Preferences > Maven > Discovery > Open Catalog_ and search
+     for _Dependency_ and install.
+
+  3. The [Google Java Format plugin for Eclipse](https://github.com/google/google-java-format/).
+     Download the [latest version](https://github.com/google/google-java-format/releases/).
+     and place the jar into your Eclipse installation's `dropins/` directory
+     (on MacOS this may be in `Eclipse.app/Contents/Eclipse/dropins/`).
 
 1. Maven 3.5.0 or later.  Although m2eclipse is bundled with its own Maven install,
    Maven is necessary to test command-line builds.
@@ -65,7 +74,9 @@ $ mvn -Declipse.target=neon package
 We normally put production code into a bundle and tests as a fragment hosted
 by that bundle, put under the `plugins/` directory.
 For now we have been committing both the `pom.xml` and Eclipse's
-`.project`, `.classpath`, and `.settings/` files.
+`.project`, `.classpath`, and `.settings/` files.  We have a master set 
+of project settings in [`eclipse/settings`](eclipse/settings/); see the
+[`README.md`](eclipse/settings/README.md) for more details.
 
 Our CI process is configured to run our tests with JaCoCo, which requires
 some additional configuration to add new bundles and fragments
@@ -291,6 +302,12 @@ the identifiers are not p2 identifiers, and so features do not
 require the `.feature.group` suffix.
 
 
+## Other Miscellaneous Dev Tasks
+
+### Updating IDE settings
+
+See [`eclipse/settings/`](eclipse/settings/README.md) for details.
+
 ### Configuring Maven/Tycho Toolchains for CI Builds
 
 _Note: this section is only relevant for configuring CI builds_

eclipse/settings/README.md

@@ -0,0 +1,80 @@
+# Project Settings for Eclipse
+
+This project contains the canonical set of Eclipse `.settings/`
+files for Cloud Tools for Eclipse.  These settings configure Eclipse
+to use the [Google Style for Java][google-style-java].
+
+The settings currently reflect the following choices:
+
+  - uses the [Google Java Format plugin for Eclipse](google-java-format),
+    which requires developing with Eclipse Oxygen (4.7) or later
+  - unnecessary declared checked exceptions on methods are _errors_
+  - switch missing default case are _warnings_
+  - resource leaks are _errors_
+  - potential resource leaks are _warnings_
+  - serializable classes without `serialVersionUID` are _ignored_
+  - redundant generic type argument are _errors_
+  - disable warnings on non-externalized strings / $NON-NLS-x$ due to
+    https://github.com/google/google-java-format/issues/221
+
+
+## Updating / Applying the Settings
+
+The settings require installing the [Google Java Format plugin for
+Eclipse][google-java-format].  Installing the format plugin requires
+downloading the [latest release][google-java-format-release] (named
+`google-java-format-eclipse-plugin_XXXX.jar`) and placing the jar
+in your Eclipse installation's `dropins/` directory (on MacOS, in
+`Eclipse.app/Content/Eclipse/dropins/`).
+
+Updating and applying the settings files is a two-step process based
+around the [`eclipse-settings-maven-plugin`][esmp] Maven plugin.
+
+  [esmp]: https://github.com/BSI-Business-Systems-Integration-AG/eclipse-settings-maven-plugin
+  [google-style-java]: https://google.github.io/styleguide/javaguide.html
+  [google-java-format]: https://github.com/google/google-java-format
+  [google-java-format-release]: https://github.com/google/google-java-format/releases
+
+### Step 0: Change the Canonical Settings (OPTIONAL)
+
+To update the settings, change the settings for one project and
+then copy in the changed files from its `.settings/` directory into
+`files/`.  Note that if a new file is added, the new file must be
+reflected into the `eclipse-settings-maven-plugin`'s configuration
+(defined in `plugins/pom.xml`).
+
+### Step 1: Publishing the Settings Files
+
+This project (`eclipse/settings/`) publishes the settings files as
+a Maven `jar` artifact.  This published jar is then used by the
+`eclipse-settings-maven-plugin` as the source for the settings files.
+The settings files themselves are found in in this project under
+[`files/`](files/).
+
+To publish the settings, run the following to assemble the jar and
+install it in your local repository (`~/.m2/repository/`)
+
+```sh
+$ cd eclipse/settings
+$ mvn install
+```
+
+### Step 2: Applying the Settings
+
+Once the settings are available, the second step invokes the
+`eclipse-settings-maven-plugin`'s `eclipse-settings` goal to resolve
+the settings artifact and extract the contents to the appropriate
+locations.  Run the following:
+
+```
+$ cd plugins
+$ mvn --no-snapshot-updates -Dtycho.mode=maven eclipse-settings:eclipse-settings
+```
+
+The `--no-snapshot-updates` is required to resolve the settings
+artifact from the local repository.  The `-Dtycho.mode=maven` speeds
+up the process.
+
+### Step 3: Commit
+
+You should then commit the result.

eclipse/settings/files/org.eclipse.core.resources.prefs

@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+encoding/<project>=UTF-8

eclipse/settings/files/org.eclipse.core.runtime.prefs

@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+line.separator=\n