Merge pull request #2194 from scalacenter/add-scala-3-contributing-guide

Add scala 3 contributing guide - MVP

Author: anatoliykmetyuk

_config.yml

@@ -116,6 +116,16 @@ defaults:
       overview-name: "Scala 3 Migration Guide"
       layout: multipage-overview
       permalink: "/scala3/guides/migration/:title.html"
+  -
+    scope:
+      path: "_overviews/scala3-contribution"
+    values:
+      scala3: true
+      partof: scala3-contribution
+      type: section
+      overview-name: "Guide to Scala 3 Compiler Contribution"
+      layout: multipage-overview
+      permalink: "/scala3/guides/contribution/:title.html"
   -
     scope:
       path: "_overviews/scala3-macros"

_data/scala3-doc-nav-header.yml

@@ -7,6 +7,8 @@
       url: "/scala3/getting-started.html"
     - title: Scala 3 Book
       url: "/scala3/book/introduction.html"
+    - title: Contributing Guide
+      url: "/scala3/guides/contribution/contribution-intro.html"
     - title: Macro Tutorial
       url: "/scala3/guides/macros/index.html"
 - title: Migrate
@@ -15,3 +17,5 @@
   url: "/scala3/reference/overview.html"
 - title: API
   url: "https://scala-lang.org/api/3.x/"
+- title: Contributing Guide
+  url: "/scala3/guides/contribution/contribution-intro.html"

_ja/scala3/contribute-to-docs.md

@@ -34,7 +34,7 @@ Scala 3 の高品質なドキュメンテーションを作るためのいくつ
 - [Issues](https://github.com/scala/docs.scala-lang/issues)
 
 ## Macros Tutorial
-[Macros Tutorial](/scala3/guides/macros)は Nicolas Stucki 氏 が書いている。この本では Scala 3 のマクロとそのベストプラクティスについて詳しく説明している。 
+[Macros Tutorial](/scala3/guides/macros)は Nicolas Stucki 氏 が書いている。この本では Scala 3 のマクロとそのベストプラクティスについて詳しく説明している。
 
 - [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-macros)
 - [Issues](https://github.com/scala/docs.scala-lang/issues)
@@ -45,6 +45,12 @@ Scala 3 の高品質なドキュメンテーションを作るためのいくつ
 - [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration)
 - [Issues](https://github.com/scalacenter/docs.scala-lang/issues)
 
+## Scala 3 Contribution Guide
+[Scala 3 Contribution Guide](/scala3/guides/contribution/contribution-intro.html)
+Scala 3 コンパイラとライブラリへの貢献と内部に関する包括的な概要が含まれています
+
+- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution)
+- [Issues](https://github.com/scala/docs.scala-lang/issues)
 
 ## Scala 3 Language Reference
 The [Dotty reference](/scala3/reference/overview.html) は Scala 3 になる予定である。これにはさまざまな言語仕様に関する公式のプレゼンテーションや技術的情報が含まれている。
@@ -54,4 +60,3 @@ The [Dotty reference](/scala3/reference/overview.html) は Scala 3 になる予
 
 
 [scala3-book]: {% link _overviews/scala3-book/introduction.md %}
-

_ja/scala3/new-in-scala3.md

@@ -13,6 +13,7 @@ Scala 3 は Scala 2 から大幅な改善が行われ、さまざまな新機能
 - [Syntax Summary][syntax-summary] では Scala 3 で新しく追加されたシンタックスを解説している。
 - [Language Reference][reference] を見ればScala 2 と Scala 3 の変更点を詳しく確認できる。
 - Scala 2 から Scala 3 への移行を考えている方は[Migration Guide][migration] を参照。
+- [Contribution Guide][contribution] は、問題を修正するためのガイドを含め、コンパイラーをさらに深く掘り下げます。
 
 ## What's new in Scala 3
 Scala 3 は Scala 2 を徹底的に見直して再設計されている。核心部分で、型システムの多くの面が変更されより原理原則に基づいたものになった。この変更によって新機能(ユニオン型)が使えるようになったことにくわえて、なにより型システムがさらに使いやすくなった。 例えば、[型推論][type-inference] や overload resolution が改善された.
@@ -37,7 +38,7 @@ Scala 3 ではひとつの強力な機能として`implicit`を提供するの
 - **Providing Type-class instances**. [Given instances][contextual-givens] を使ってある型に対応する _canonical value_ を定義することができる。実装を公開することなく、型クラスを使ったプログラミングをよりわかりやすく書ける。
 
 - **Retroactively extending classes**. Scala 2 では拡張メソッドは暗黙の変換か implicit classを使って書くことができた. 一方 Scala 3 では [extension methods][contextual-extension] が直接的に言語仕様に含まれているのでよりわかりやすいエラーメッセージを表示できる。型推論も改善された。
-- **Viewing one type as another**. 暗黙の変換は型クラス`Conversion`のインスタンスとしてゼロから [再設計][contextual-conversions]された。 
+- **Viewing one type as another**. 暗黙の変換は型クラス`Conversion`のインスタンスとしてゼロから [再設計][contextual-conversions]された。
 - **Higher-order contextual abstractions**. 全く新しい機能である  [context functions][contextual-functions] は暗黙の引数をとる関数型を第一級オブジェクトとして扱う。この機能はライブラリ作者にとって重要である。また、簡潔なドメイン特化言語(DSL)を記述するのにも役立つ。
 
 - **Actionable feedback from the compiler**. コンパイラが暗黙の引数の解決に失敗した場合、解決に役立つ [import suggestions](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html) を提示する。
@@ -99,6 +100,7 @@ Scala 3 のメタプログラミングについてもっと知りたいかたは
 [reference]: {{ site.scala3ref }}/overview.html
 [creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html
 [migration]: {% link _overviews/scala3-migration/compatibility-intro.md %}
+[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %}
 
 [implicits]: {{ site.scala3ref }}/contextual.html
 [contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html

_overviews/scala3-contribution/arch-context.md

@@ -0,0 +1,43 @@
+---
+title: Contexts
+type: section
+description: This page describes symbols in the Scala 3 compiler.
+num: 18
+previous-page: arch-symbols
+next-page:
+---
+
+> (The following is work in progress), adapted from dotty.epfl.ch
+
+The `Context` contains the state of the compiler, for example
+
+  * `settings`
+  * `freshNames` (`FreshNameCreator`)
+  * `period` (run and phase id)
+  * `compilationUnit`
+  * `phase`
+  * `tree` (current tree)
+  * `typer` (current typer)
+  * `mode` (type checking mode)
+  * `typerState` (for example undetermined type variables)
+  * ...
+
+### Contexts in the typer
+The type checker passes contexts through all methods and adapts fields where
+necessary, e.g.
+
+```scala
+case tree: untpd.Block => typedBlock(desugar.block(tree), pt)(ctx.fresh.withNewScope)
+```
+
+A number of fields in the context are typer-specific (`mode`, `typerState`).
+
+### In other phases
+Other phases need a context for many things, for example to access the
+denotation of a symbols (depends on the period). However they typically don't
+need to modify / extend the context while traversing the AST. For these phases
+the context can be simply an implicit class parameter that is then available in
+all members.
+
+**Careful**: beware of memory leaks. Don't hold on to contexts in long lived
+objects.

_overviews/scala3-contribution/arch-intro.md

@@ -0,0 +1,18 @@
+---
+title: High Level Architecture
+type: chapter
+description: This page introduces the high level architecture of the Scala 3 compiler.
+num: 12
+previous-page: procedures-checklist
+next-page: arch-lifecycle
+---
+
+This chapter of the guide describes the architecture and concepts of `dotc`,
+the Scala 3 compiler, including answers to questions such as:
+- "What are the transformations that happen to my code?"
+- "How do I run a compiler programatically?"
+- "What are symbols, denotations, names and types?"
+- "What is a compiler phase?"
+- "What is the compiler Context?"
+
+and many more.

_overviews/scala3-contribution/arch-lifecycle.md

@@ -0,0 +1,95 @@
+---
+title: Compiler Overview
+type: section
+description: This page describes the lifecycle for the Scala 3 compiler.
+num: 13
+previous-page: arch-intro
+next-page: arch-phases
+---
+
+As mentioned in [what is a compiler?][1] `dotc` produces programs that can run on your machine,
+first by verifying its input is a valid Scala program, and then transforming it into a
+representation that can run on one of Scala's target platforms.
+
+## Introducing the Compiler's Lifecycle
+
+#### Core
+At a high level, `dotc` centers its work around a [Compiler][4], which maintains an ordered
+list of [phases][3], and is responsible for creating new [runs][2].
+A run is a complete iteration of the compiler's phases over a list of input sources.
+A compiler is designed to be reusable and can create many runs over its lifetime.
+
+#### Runs
+During a run, the input sources are converted to [compilation units][5] (i.e. the abstraction of
+compiler state associated with each input source); then iteratively: a single phase is applied to
+every compilation unit before progressing to the next phase.
+
+#### Phases
+A phase is an abstract transformation over a compilation unit, it is usually responsible
+for transforming the trees and types representing the code of a source file. The primary phases of
+the compiler are the `parser`, which converts text that matches Scala's
+[syntax][10] into abstract syntax trees, ASTs, and the `typer`, which checks that
+trees conform to expected types, and performs other operations such as implicit search.
+[You can read more about phases here][9].
+
+#### Drivers
+
+The core compiler also requires a lot of state to be initialised before use, such as [settings][8]
+and the [Context]. For convenience, the [Driver] class contains high level functions for
+configuring the compiler and invoking it programatically. The object [Main] inherits from `Driver`
+and is invoked by the `scalac` script.
+
+<!-- #### Further Reading -->
+> [Read more about a compiler's lifecyle][6].
+
+## Code Structure
+
+The code of the compiler is found in the package [dotty.tools][7],
+containing the following sub-packages:
+```scala
+tools // contains helpers and the `scala` generic runner
+├── backend // Compiler backends (currently JVM and JS)
+├── dotc // The main compiler, with subpackages:
+│   ├── ast // Abstract syntax trees
+│   ├── classpath
+│   ├── config // Compiler configuration, settings, platform specific definitions.
+│   ├── core // Core data structures and operations, with specific subpackages for:
+│   │   ├── classfile // Reading of Java classfiles into core data structures
+│   │   ├── tasty // Reading and writing of TASTY files to/from core data structures
+│   │   └── unpickleScala2 // Reading of Scala2 symbol information into core data structures
+│   ├── decompiler // pretty printing TASTY as code
+│   ├── fromtasty // driver for recompilation from TASTY
+│   ├── interactive // presentation compiler and code completions
+│   ├── parsing // Scanner and parser
+│   ├── plugins // compile plugin definitions
+│   ├── printing // Pretty-printing trees, types and other data
+│   ├── profile // internals for profiling the compiler
+│   ├── quoted // internals for quoted reflection
+│   ├── reporting // Reporting of error messages, warnings and other info.
+│   ├── rewrites // Helpers for rewriting Scala 2's constructs into Scala 3's.
+│   ├── sbt // Helpers for communicating with the Zinc compiler.
+│   ├── semanticdb // Helpers for exporting semanticdb from trees.
+│   ├── transform // Miniphases and helpers for tree transformations.
+│   ├── typer // Type-checking
+│   └── util // General purpose utility classes and modules.
+├── io // Helper modules for file access and classpath handling.
+├── repl // REPL driver and interaction with the terminal
+├── runner // helpers for the `scala` generic runner script
+└── scripting // scala runner for the -script argument
+```
+
+[1]: {% link _overviews/scala3-contribution/contribution-intro.md %}/#what-is-a-compiler
+[2]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Run.scala
+[3]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/core/Phases.scala
+[4]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Compiler.scala
+[5]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/CompilationUnit.scala
+[6]: {% link _overviews/scala3-contribution/arch-time.md %}
+[7]: https://github.com/lampepfl/dotty/tree/master/compiler/src/dotty/tools
+[8]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala
+[9]: {% link _overviews/scala3-contribution/arch-phases.md %}
+[10]: {% link _scala3-reference/syntax.md %}
+[Main]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Main.scala
+[Driver]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Driver.scala
+[Compiler]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Compiler.scala
+[Run]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Run.scala
+[Context]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/core/Contexts.scala

_overviews/scala3-contribution/arch-phases.md

@@ -0,0 +1,107 @@
+---
+title: Compiler Phases
+type: section
+description: This page describes the phases for the Scala 3 compiler.
+num: 14
+previous-page: arch-lifecycle
+next-page: arch-types
+---
+
+As described in the [compiler overview][1], `dotc` is divided into a list of [phases][Phase],
+specified in the [Compiler] class.
+
+#### Printing the phases of the Compiler
+
+a flattened list of all the phases can be displayed by invoking
+the compiler with the `-Xshow-phases` flag:
+```
+$ scalac -Xshow-phases
+```
+
+## Phase Groups
+
+In class [Compiler] we can access the list of phases with the method `phases`:
+
+```scala
+def phases: List[List[Phase]] =
+  frontendPhases ::: picklerPhases ::: transformPhases ::: backendPhases
+```
+
+We see that phases are actually grouped into sublists, given by the signature
+`List[List[Phase]]`; that is, each sublist forms a phase group that is then *fused* into a
+single tree traversal when a [Run] is executed.
+
+Phase fusion allows each phase of a group to be small and modular,
+(each performing a single function), while reducing the number of tree traversals
+and increasing performance.
+
+Phases are able to be grouped together if they inherit from [MiniPhase].
+
+## Phase Categories
+
+Phases fall into four categories, allowing customisation by sub-classes of [Compiler]:
+
+### `frontendPhases`
+In the main compiler these include [parser], [typer], [posttyper],
+[prepjsinterop] and phases for producing SemanticDB and communicating with the
+incremental compiler Zinc.
+The [parser] reads source programs and generates untyped abstract syntax trees, which
+in [typer] are then typechecked and transformed into typed abstract syntax trees.
+Following is [posttyper], performing checks and cleanups that require a fully typed program.
+In particular, it
+- creates super accessors representing `super` calls in traits
+- creates implementations of compiler-implemented methods,
+such as `equals` and `hashCode` for case classes.
+- marks [compilation units][2] that require inline expansion, or quote pickling
+- simplifies trees of erased definitions
+- checks variance of type parameters
+- mark parameters passed unchanged from subclass to superclass for later pruning.
+
+### `picklerPhases`
+These phases start with [pickler], which serializes typed trees
+produced by the `frontendPhases` into TASTy format. Following is [inlining],
+which expand calls to inline methods, and [postInlining] providing implementations
+of the Mirror framework for inlined calls.
+Finally are [staging], which ensures that quotes conform to the
+Phase Consistency Principle (PCP), and [pickleQuotes] which converts quoted
+trees to embedded TASTy strings.
+
+### `transformPhases`
+These phases are concerned with tranformation into lower-level forms
+suitable for the runtime system, with two sub-groupings:
+- High-level transformations: All phases from [firstTransform] to [erasure].
+  Most of these phases transform syntax trees, expanding high-level constructs
+  to more primitive ones.
+  - Some phases perform further checks on more primitive trees,
+    e.g. [refchecks] verifies that no abstract methods exist in concrete classes,
+    and [initChecker] checks that fields are not used before initialisation.
+  - The last phase in the group, [erasure] translates all
+    types into types supported directly by the JVM. To do this, it performs
+    another type checking pass, but using the rules of the JVM's type system
+    instead of Scala's.
+- Low-level transformations: All phases from `ElimErasedValueType` to
+  `CollectSuperCalls`. These further transform trees until they are essentially a
+  structured version of Java bytecode.
+
+### `backendPhases`
+These map the transformed trees to Java classfiles or SJSIR files.
+
+[1]: {% link _overviews/scala3-contribution/arch-lifecycle.md %}/#phases
+[2]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/CompilationUnit.scala
+[Compiler]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Compiler.scala
+[Phase]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/core/Phases.scala
+[MiniPhase]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/MegaPhase.scala
+[Run]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/Run.scala
+[parser]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/parsing/ParserPhase.scala
+[typer]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/typer/TyperPhase.scala
+[posttyper]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/PostTyper.scala
+[prepjsinterop]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/sjs/PrepJSInterop.scala
+[pickler]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/Pickler.scala
+[inlining]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/Inlining.scala
+[postInlining]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/PostInlining.scala
+[staging]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/Staging.scala
+[pickleQuotes]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/PickleQuotes.scala
+[refchecks]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/typer/RefChecks.scala
+[initChecker]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/init/Checker.scala
+[firstTransform]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/FirstTransform.scala
+[erasure]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/Erasure.scala