Add docs on changed features

docs/docs/reference/adts.md

@@ -108,7 +108,7 @@ The changes are specified below as deltas with respect to the Scala syntax given
         EnumDef ::=  id ClassConstr [`extends' [ConstrApps]]
                      [nl] `{’ EnumCaseStat {semi EnumCaseStat} `}’
 
-2. Cases of enums are defined as follows:
+ 2. Cases of enums are defined as follows:
 
         EnumCaseStat  ::=  {Annotation [nl]} {Modifier} EnumCase
         EnumCase      ::=  `case' (EnumClassDef | ObjectDef | ids)

docs/docs/reference/changed/lazy-vals.md

@@ -0,0 +1,19 @@
+---
+layout: doc-page
+title: Changed: Lazy Vals and @volatile
+---
+
+Lazy val initialization no longer guarantees safe publishing. This change was done
+to avid the performance overhead of thread synchonization because many lazy vals are only used in a single-threaded context.
+
+To get back safe publishing you need to annotate a lazy val with `@volatile`. In
+
+    @volatile lazy val x = expr
+
+it is guaranteed that readers of a lazy val will see the value of `x`
+once it is assigned.
+
+The [ScalaFix](https://scalacenter.github.io/scalafix/) rewrite tool
+as well as Dotty's own `-migration` option will rewrite all normal
+lazy vals to volatile ones in order to keep their semantics compatible
+with current Scala's.

docs/sidebar.yml

@@ -35,6 +35,12 @@ sidebar:
               url: docs/reference/auto-parameter-tupling.html
             - title: Named Type Arguments
               url: docs/reference/named-typeargs.html
+        - title: Changed Features
+          subsection:
+            - title: Volatile Lazy Vals
+              url: docs/reference/changed/lazy-vals.md
+            - title: Structural Types
+              url: docs/reference/changed/structural-types.md
         - title: Dropped Features
           subsection:
             - title: DelayedInit