Document that local optimisations assumes final fields are final

Author: OlivierBlanvillain

docs/docs/reference/optimisations.md

@@ -0,0 +1,8 @@
+---
+layout: doc-page
+title: "Local Optimisations"
+---
+
+The Dotty compiler implements several local optimisations to generate faster bytecode. These optimisations can be enabled by compiling with the `-optimise` flag. The current best source of documentation about what tree transformations are performed under `-optimise` is the Scaladoc classes in the [localopt package](https://github.com/lampepfl/dotty/tree/master/compiler/src/dotty/tools/dotc/transform/localopt).
+
+Local optimisations assumes no use of Java Reflection to mutate static final fields.

docs/sidebar.yml

@@ -51,6 +51,8 @@ sidebar:
               url: docs/reference/auto-parameter-tupling.html
             - title: Named Type Arguments
               url: docs/reference/named-typeargs.html
+            - title: Local Optimisations
+              url: docs/reference/optimisations.html
         - title: Changed Features
           subsection:
             - title: Volatile Lazy Vals