Retain the documentation

docs/_docs/reference/language-versions/binary-compatibility.md

@@ -0,0 +1,12 @@
+---
+layout: doc-page
+title: "Binary Compatibility"
+---
+
+In Scala 2 different minor versions of the compiler were free to change the way how they encode different language features in JVM bytecode so each bump of the compiler's minor version resulted in breaking binary compatibility and if a project had any Scala dependencies they all needed to be (cross-)compiled to the same minor Scala version that was used in that project itself. On the contrary, Scala 3 has a stable encoding into JVM bytecode.
+
+In addition to classfiles the compilation process in Scala 3 also produces files with `.tasty` extension. The [TASTy](https://docs.scala-lang.org/scala3/guides/tasty-overview.html) format is an intermediate representation of Scala code containing full information about sources together with information provided by the typer. Some of this information is lost during generation of bytecode so Scala 3 compilers read TASTy files during compilation in addition to classfiles to know the exact types of values, methods, etc. in already compiled classes (although compilation from TASTy files only is also possible). TASTy files are also typically distributed together with classfiles in published artifacts.
+
+TASTy format is extensible but it preserves backward compatibility and the evolution happens between minor releases of the language. This means a Scala compiler in version `3.x1.y1` is able to read TASTy files produced by another compiler in version `3.x2.y2` if `x1 >= x2` (assuming two stable versions of the compiler are considered - `SNAPSHOT` or `NIGHTLY` compiler versions can read TASTy in an older stable format but their TASTY versions are not compatible between each other even if the compilers have the same minor version; also compilers in stable versions cannot read TASTy generated by an unstable version).
+
+TASTy version number has the format of `<major_version>.<minor_version>-<experimental_version>` and the numbering changes in parallel to language releases in such a way that a bump in language minor version corresponds to a bump in TASTy minor version (e.g. for Scala `3.0.0` the TASTy version is `28.0-0`). Experimental version set to 0 signifies a stable version while others are considered unstable/experimental. TASTy version is not strictly bound to the data format itself - any changes to the API of the standard library also require a change in TASTy minor version.

docs/_docs/reference/language-versions/language-versions.md

@@ -0,0 +1,6 @@
+---
+layout: index
+title: "Language Versions"
+---
+
+Additional information on interoperability and migration between Scala 2 and 3 can be found [here](https://docs.scala-lang.org/scala3/guides/migration/compatibility-intro.html).

docs/_docs/reference/language-versions.md → docs/_docs/reference/language-versions/source-compatibility.md

@@ -1,10 +1,12 @@
 ---
 layout: doc-page
-title: "Language Versions"
+title: "Source Compatibility"
 movedTo: https://docs.scala-lang.org/scala3/reference/language-versions.html
 ---
 
-The default Scala language version currently supported by the Dotty compiler is [`3.0`](https://scala-lang.org/api/3.x/scala/runtime/stdLibPatches/language$$3/0$.html). There are also other language versions that can be specified instead:
+Scala 3 does NOT guarantee source compatibility between different minor language versions (e.g. some syntax valid in 3.x might get deprecated and then phased out in 3.y for y > x). There are also some syntax structures that were valid in Scala 2 but are not anymore in Scala 3. However the compiler provides a possibility to specify the desired version of syntax used in a particular file or globally for a run of the compiler to make migration between versions easier.
+
+The default Scala language syntax version currently supported by the Dotty compiler is [`3.0`](https://scala-lang.org/api/3.x/scala/runtime/stdLibPatches/language$$3/0$.html). There are also other language versions that can be specified instead:
 
 - [`3.0-migration`](https://scala-lang.org/api/3.x/scala/runtime/stdLibPatches/language$$3/0-migration$.html): Same as `3.0` but with a Scala 2 compatibility mode that helps moving Scala 2.13 sources over to Scala 3. In particular, it
 

docs/sidebar.yml

@@ -124,18 +124,25 @@ subsection:
         directory: experimental
         index: reference/experimental/overview.md
         subsection:
+          - page: reference/experimental/fewer-braces.md
           - page: reference/experimental/canthrow.md
           - page: reference/experimental/erased-defs.md
           - page: reference/experimental/erased-defs-spec.md
+            hidden: true
           - page: reference/experimental/named-typeargs.md
           - page: reference/experimental/named-typeargs-spec.md
+            hidden: true
           - page: reference/experimental/numeric-literals.md
           - page: reference/experimental/explicit-nulls.md
           - page: reference/experimental/main-annotation.md
           - page: reference/experimental/cc.md
           - page: reference/experimental/tupled-function.md
       - page: reference/syntax.md
-      - page: reference/language-versions.md
+      - title: Language Versions
+        index: reference/language-versions/language-versions.md
+        subsection:
+          - page: reference/language-versions/source-compatibility.md
+          - page: reference/language-versions/binary-compatibility.md
       - page: reference/soft-modifier.md
       - page: reference/features-classification.md
   - title: Contributing