Sync with the stable documentation branch

.github/workflows/ci.yaml

@@ -2,13 +2,9 @@ name: Dotty
 
 on:
   push:
-    branches-ignore:
-      - 'language-reference-stable'
     tags:
       - '**'
   pull_request:
-    branches-ignore:
-      - 'language-reference-stable'
   schedule:
     - cron: '0 3 * * *'  # Every day at 3 AM
   workflow_dispatch:
@@ -256,6 +252,7 @@ jobs:
            github.event_name == 'pull_request'
            && !contains(github.event.pull_request.body, '[skip ci]')
            && !contains(github.event.pull_request.body, '[skip community_build]')
+           && !contains(github.event.pull_request.body, '[skip community_build_a]')
          )
          || (
            github.event_name == 'workflow_dispatch'
@@ -303,6 +300,7 @@ jobs:
            github.event_name == 'pull_request'
            && !contains(github.event.pull_request.body, '[skip ci]')
            && !contains(github.event.pull_request.body, '[skip community_build]')
+           && !contains(github.event.pull_request.body, '[skip community_build_b]')
          )
          || (
            github.event_name == 'workflow_dispatch'
@@ -350,6 +348,7 @@ jobs:
            github.event_name == 'pull_request'
            && !contains(github.event.pull_request.body, '[skip ci]')
            && !contains(github.event.pull_request.body, '[skip community_build]')
+           && !contains(github.event.pull_request.body, '[skip community_build_c]')
          )
          || (
            github.event_name == 'workflow_dispatch'

.github/workflows/cla.yml

@@ -1,9 +1,11 @@
 name: Scala CLA
 on:
   pull_request:
+    branches-ignore:
+      - 'language-reference-stable'
   push:
     branches:
-      - 'language-reference-backport'
+      - 'language-reference-stable'
 permissions:
   contents: write
   pull-requests: write

.github/workflows/language-reference.yaml

@@ -1,4 +1,4 @@
-name: language-reference-documentation
+name: Language reference documentation
 
 on:
   push:
@@ -14,14 +14,14 @@ permissions:
 
 jobs:
   build-and-push:
+    name: Build reference documentation and push it
     permissions:
       contents: write  # for Git to git push
-      pull-requests: write  # for peter-evans/create-pull-request to create a PR
     runs-on: ubuntu-latest
     steps:
       - name: Get current date
         id: date
-        run: echo "::set-output name=date::$(date +'%Y-%m-%d')"
+        run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
 
       - name: Git Checkout
         uses: actions/checkout@v3
@@ -67,26 +67,22 @@ jobs:
           fi
           cd ..
 
-      - name: Merge changes to main
-        if: github.event_name == 'push'
-        run: |
-          cd dotty
-          git fetch origin main:main
-          git checkout main
-          git config user.name gh-actions
-          git config user.email [email protected]
-          git merge language-reference-stable
-          cd ..
-
-      - name: Create pull request with backport to main
-        if: github.event_name == 'push'
-        uses: peter-evans/create-pull-request@v4
+  backport-to-main:
+    name: Create pull request with backport to main
+    permissions:
+      pull-requests: write  # for repo-sync/pull-request to create a PR
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v3
+      - uses: repo-sync/pull-request@v2
         with:
-          path: dotty
-          branch: language-reference-backport
-          labels: area:documentation
-          title: Backport changes from stable documentation branch
-          body: This pull request is created automatically after push to stable documentation branch and backports the changes
-          reviewers: pikinier20,julienrf
-          assignees: pikinier20
+          destination_branch: main
+          pr_label: area:documentation
+          pr_title: Sync with the stable documentation branch
+          pr_body: |
+            This pull request is syncing the main with changes from language-reference-stable.
+
+            It was created automatically after ${{ github.event.head_commit.id }} by @${{ github.event.head_commit.author.username }}
+          pr_assignee: ${{ github.event.head_commit.author.username }}
 

docs/_assets/css/frontpage.css

@@ -28,6 +28,7 @@ h1#main {
 /* navigation */
 header {
   font-size: 24px;
+  margin-block-end: calc(2* var(--base-spacing));
 }
 
 header .nav-item i {

docs/_docs/contributing/procedures/index.md

@@ -0,0 +1,4 @@
+---
+layout: index
+title: Procedures
+---

docs/_docs/contributing/tools/index.md

@@ -0,0 +1,4 @@
+---
+layout: index
+title: IDEs and Tools
+---

docs/_docs/internals/gadts.md

@@ -1,4 +1,9 @@
-# GADTs - Broad overview
+---
+layout: doc-page
+title: "GADTs - Broad overview"
+---
+
+## Introduction
 
 There are multiple levels to the implementation. They deal with slightly different problems. The most important levels are the following ones:
 
@@ -18,9 +23,9 @@ There are also other parts to supporting GADTs. Roughly in order of importance,
     1.  Attachment key is named `inferredGadtConstraints`.
 4.  When we select members on a type that may have GADT constraints, we perform special "healing" by approximating the type using those constraints. We cannot take the constraints into account because member lookup is cached, and GADT constraints are only valid for specific scopes.
 
-# Useful widgets
+## Useful widgets
 
-## Expr
+### Expr
 
 This is the classical GADT example:
 
@@ -36,7 +41,7 @@ enum Expr[T] {
 }
 ```
 
-## EQ
+### EQ
 
 The following enum will result in an equality constraint between `S` and `T` if we match on it:
 
@@ -46,7 +51,7 @@ enum EQ[S, T] {
 }
 ```
 
-## SUB
+### SUB
 
 The following enum will result in a subtyping constraint `S <: T` if we match on it:
 
@@ -56,9 +61,9 @@ enum SUB[-S, +T] {
 }
 ```
 
-# Details of above
+## Details of above
 
-## What abstract types can have GADT constraints
+### What abstract types can have GADT constraints
 
 Right now, we record GADT constraints for:
 
@@ -67,9 +72,9 @@ Right now, we record GADT constraints for:
 
 There is a branch on the way which will also record them for type members (so path-dependent types) and singleton types. It has a paper associated: "Implementing path-depepdent GADTs for Scala 3".
 
-## What are necessary relationships? Any examples?
+### What are necessary relationships? Any examples?
 
-### Covariance means no constraint is necessary
+#### Covariance means no constraint is necessary
 
 Standard (non-case) classes allow "strange" inheritance which means that we cannot infer any information from covariant type parameters.
 
@@ -90,7 +95,7 @@ class Weird(list: List[String]) extends IntList with Expr[Nothing]
 
 Case classes have a special check which disallows inheritance like `Weird`. This means we can infer extra information from them.
 
-## Breaking down the constraints
+### Breaking down the constraints
 
 ```scala
 class Expr[A]
@@ -113,9 +118,9 @@ def foo[T](e: Expr[List[T]]): T =
   }
 ```
 
-## Relation betweeen GadtConstraint and OrderingConstraint
+### Relation betweeen GadtConstraint and OrderingConstraint
 
-### Internal and external types
+#### Internal and external types
 
 GadtConstraint uses OrderingConstraint as the datastructure to record information about GADT constraints.
 
@@ -127,9 +132,9 @@ To solve this, GadtConstraint internally creates TypeParamRefs which it adds to
 
 The TypeParamRefs and TypeVars registered in one constraint cannot ever be present in types mentioned in the other type constraint. The internal TypeParamRefs and TypeVars cannot ever leak out of the GadtConstraint. We cannot ever record a bound in GadtConstraint which mentions TypeParamRefs used for type inference. (That part is ensured by the way TypeComparer is organised &#x2013; we will always try to record bounds in the "normal" constraint before recording a GADT bound.)
 
-# Other details
+## Other details
 
-## TypeComparer approximations
+### TypeComparer approximations
 
 TypeComparer sometimes approximates the types it compares. Let's see an example based on these definitions:
 
@@ -142,11 +147,11 @@ when comparing if `IntList <: Expr[Int]`, `TypeComparer` will approximate `IntLi
 
 The variables which TypeComparer sets are `approxState` and `frozenGadt`.
 
-## Necessary/sufficient either
+### Necessary/sufficient either
 
 TypeComparer sometimes needs to approximate some constraints, specifically when dealing with intersection and union types. The way this approximation works changes if we're currently inferring GADT constraints. This is hopefully documented well in TypeComparer in doc comments for `necessaryEither` and `sufficientEither`.
 
-## Types bound in patterns
+### Types bound in patterns
 
 ```scala
 (list : List[Int]) match {
@@ -161,7 +166,7 @@ TypeComparer sometimes needs to approximate some constraints, specifically when
 }
 ```
 
-## Internal structure of OrderingConstraint
+### Internal structure of OrderingConstraint
 
 Imagine we have two type parameters in scope, `A` and `B`.
 
@@ -184,19 +189,19 @@ B <: A
 
 The first two constraints are "entries" &#x2013; they are easy to look up whenever we ask for bounds of `A` or `B`. The third constraint is an ordering &#x2013; it helps with correctly propagating the bounds we record.
 
-# Possible broad improvements
+## Possible broad improvements
 
-## Allow OrderingConstraint to record bounds for things other than TypeParamRefs
+### Allow OrderingConstraint to record bounds for things other than TypeParamRefs
 
 This would mean we no longer need to keep the bidirectional mapping in GadtConstraint.
 
-## Not mixing OrderingConstraint and ConstraintHandling in GadtConstraint
+### Not mixing OrderingConstraint and ConstraintHandling in GadtConstraint
 
 GadtConstraint right now mixes OrderingConstraint and ConstraintHandling. The first one is supposed to be the immutable constraint datastructure. The second one implements mutable functionality around a variable containing the immutable datastructure.
 
 GadtConstraint mixes them both. Things would be better organised if GadtConstraint was split like the normal constraint.
 
-## Creating a separate TypeComparer for breaking down types into GADT constraints
+### Creating a separate TypeComparer for breaking down types into GADT constraints
 
 TypeComparer is biased towards one specific way of approximating constraints. When we infer types, it's ok to be "optimistic". When inferring GADT constraints, we should be as pessimistic as possible, in order to only infer constraints which are necessary.
 

docs/_docs/reference/contextual/derivation.md

@@ -284,7 +284,7 @@ Note the following properties of `Mirror` types,
 + The methods `ordinal` and `fromProduct` are defined in terms of `MirroredMonoType` which is the type of kind-`*`
   which is obtained from `MirroredType` by wildcarding its type parameters.
 
-### Implementing `derived` with `Mirror`
+## Implementing `derived` with `Mirror`
 
 As seen before, the signature and implementation of a `derived` method for a type class `TC[_]` are arbitrary, but we expect it to typically be of the following form:
 
@@ -484,7 +484,7 @@ The framework described here enables all three of these approaches without manda
 For a brief discussion on how to use macros to write a type class `derived`
 method please read more at [How to write a type class `derived` method using macros](./derivation-macro.md).
 
-### Syntax
+## Syntax
 
 ```
 Template          ::=  InheritClauses [TemplateBody]

docs/_docs/reference/other-new-features/opaques-details.md

@@ -40,7 +40,7 @@ object o:
 
 In this case we have inside the object (also for non-opaque types) that `o.T` is equal to
 `T` or its expanded form `o.this.T`. Equality is understood here as mutual subtyping, i.e.
-`o.T <: o.this.T` and `o.this.T <: T`. Furthermore, we have by the rules of opaque type aliases
+`o.T <: o.this.T` and `o.this.T <: o.T`. Furthermore, we have by the rules of opaque type aliases
 that `o.this.T` equals `R`. The two equalities compose. That is, inside `o`, it is
 also known that `o.T` is equal to `R`. This means the following code type-checks:
 

docs/_docs/reference/other-new-features/opaques.md

@@ -174,6 +174,6 @@ val z = l2(3.1)
 l1.mul(x, y) // type checks
 l1.mul(x, z) // error: found l2.Logarithm, required l1.Logarithm
 ```
-In general, one can think of an opaque type as being only transparent in the scope of `private[this]`.
+In general, one can think of an opaque type as being only transparent in the scope of `private[this]` (unless the type is a top level definition - in this case, it's transparent only within the file it's defined in).
 
 [More details](opaques-details.md)

docs/_layouts/doc-page.html

@@ -5,9 +5,7 @@
 <main>
   <header>
     {% if urls.editSource %}
-    <a class="text-button with-link body-small" href="{{ urls.editSource }}">
-      Edit this page on GitHub
-    </a>
+    <a class="text-button with-link body-small" href="{{ urls.editSource }}">Edit this page on GitHub</a>
     {% endif %}
     <h1 class="h600">{{ page.title }}</h1>
   </header>

docs/_layouts/index.html

@@ -1,15 +1,24 @@
 ---
 layout: static-site-main
 ---
-<h1>{{ page.title }}</h1>
-
-{{ content }}
-
-<h2>Table of Contents</h2>
-<ul class="table-of-contents">
-  {% for subpage in site.subpages %}
-      <li>
-          <a href="{{ subpage.url }}">{{ subpage.title }}</a>
-      </li>
-  {% endfor %}
-</ul>
+
+<main>
+  <header>
+    {% if urls.editSource %}
+    <!--<a class="text-button with-link body-small" href="{{ urls.editSource }}">Edit this page on GitHub</a>-->
+    {% endif %}
+    <h1 class="h600">{{ page.title }}</h1>
+  </header>
+
+  {{ content }}
+
+  <h2 class="h500">Table of Contents</h2>
+  <ul class="table-of-contents">
+    {% for subpage in site.subpages %}
+        <li>
+            <a href="{{ subpage.url }}">{{ subpage.title }}</a>
+        </li>
+    {% endfor %}
+  </ul>
+
+</main>

docs/_layouts/main.html

@@ -1,9 +1,5 @@
 ---
 layout: base
-extraJS:
-  - js/contributors.js
-extraCSS:
-  - css/content-contributors.css
 ---
 
 <div id="content-wrapper">{{ content }}</div>