[FLINK-12461] Document Scala 2.12.x situation

docs/dev/project-configuration.md

@@ -146,6 +146,23 @@ pick the Scala version that matches their application's Scala version.
 Please refer to the [build guide]({% link flinkDev/building.md %}#scala-versions)
 for details on how to build Flink for a specific Scala version.
 
+Scala versions after 2.12.8 are not binary compatible with previous 2.12.x
+versions, preventing the Flink project from upgrading its 2.12.x builds beyond
+2.12.8.  Users can build Flink locally for latter Scala versions by following
+the above mentioned [build guide]({% link flinkDev/building.md
+%}#scala-versions). For this to work, users need to add `-Djapicmp.skip` to
+skip binary compatibility checks when building.
+
+See the [Scala 2.12.8 release
+notes](https://github.com/scala/scala/releases/tag/v2.12.8) for more details,
+the relevant quote is this:
+
+> The second fix is not binary compatible: the 2.12.8 compiler omits certain
+> methods that are generated by earlier 2.12 compilers. However, we believe
+> that these methods are never used and existing compiled code will continue to
+> work.  See the [pull request
+> description](https://github.com/scala/scala/pull/7469) for more details.
+
 ## Hadoop Dependencies
 
 **General rule: It should never be necessary to add Hadoop dependencies directly to your application.**

docs/dev/project-configuration.zh.md

@@ -146,6 +146,23 @@ pick the Scala version that matches their application's Scala version.
 Please refer to the [build guide]({% link flinkDev/building.zh.md %}#scala-versions)
 for details on how to build Flink for a specific Scala version.
 
+Scala versions after 2.12.8 are not binary compatible with previous 2.12.x
+versions, preventing the Flink project from upgrading its 2.12.x builds beyond
+2.12.8.  Users can build Flink locally for latter Scala versions by following
+the above mentioned [build guide]({% link flinkDev/building.zh.md
+%}#scala-versions). For this to work, users need to add `-Djapicmp.skip` to
+skip binary compatibility checks when building.
+
+See the [Scala 2.12.8 release
+notes](https://github.com/scala/scala/releases/tag/v2.12.8) for more details,
+the relevant quote is this:
+
+> The second fix is not binary compatible: the 2.12.8 compiler omits certain
+> methods that are generated by earlier 2.12 compilers. However, we believe
+> that these methods are never used and existing compiled code will continue to
+> work.  See the [pull request
+> description](https://github.com/scala/scala/pull/7469) for more details.
+
 ## Hadoop Dependencies
 
 **General rule: It should never be necessary to add Hadoop dependencies directly to your application.**

docs/flinkDev/building.md

@@ -130,11 +130,17 @@ Flink has APIs, libraries, and runtime modules written in [Scala](http://scala-l
 
 Since version 1.7 Flink builds with Scala version 2.11 (default) and 2.12.
 
-To build FLink against Scala 2.12, issue the following command:
+To build Flink against Scala 2.12, issue the following command:
 {% highlight bash %}
 mvn clean install -DskipTests -Dscala-2.12
 {% endhighlight %}
 
+To build against a specific binary Scala version you can use:
+{% highlight bash %}
+mvn clean install -DskipTests -Dscala-2.12 -Dscala.version=<scala version>
+{% endhighlight %}
+
+
 {% top %}
 
 ## Encrypted File Systems

docs/flinkDev/building.zh.md

@@ -140,6 +140,11 @@ Flink 有使用 [Scala](http://scala-lang.org) 来写的 API，库和运行时
 mvn clean install -DskipTests -Dscala-2.12
 {% endhighlight %}
 
+要针对特定的二进制 Scala 版本进行构建，可以使用
+{% highlight bash %}
+mvn clean install -DskipTests -Dscala-2.12 -Dscala.version=<scala version>
+{% endhighlight %}
+
 {% top %}
 
 ## 加密的文件系统