diff --git a/docs/_docs/contributing/cheatsheet.md b/docs/_docs/contributing/cheatsheet.md new file mode 100644 index 000000000000..33e85a2cf564 --- /dev/null +++ b/docs/_docs/contributing/cheatsheet.md @@ -0,0 +1,37 @@ +--- +layout: doc-page +title: Command Cheatsheet +--- + +## sbt commands + +Below is a cheat sheet of some frequently used commands to be used from SBT +console โ€“ `sbt`. + + +| Command | Description | +|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| `scala3/scalac` | Run the compiler directly, with any current changes. | +| `scala3/scala` | Run the main method of a given class name. | +| `scalac ../issues/Playground.scala` | Compile the given file โ€“ path relative to the Dotty directory. Output the compiled class files to the Dotty directory itself. | +| `scala Playground` | Run the compiled class `Playground`. Dotty directory is on classpath by default. | +| `repl` | Start REPL | +| `scala3/scalac -print-tasty Foo.tasty` | Print the TASTy of top-level class `Foo` | +| `scala3-bootstrapped/test` | Run all tests for Scala 3. (Slow, recommended for CI only) | +| `scala3-bootstrapped/publishLocal` | Build Scala 3 locally. (Use to debug a specific project) | +| `testOnly dotty.tools.dotc.CompilationTests -- *pos` | Run test (method) `pos` from `CompilationTests` suite. | +| `testCompilation sample` | In all test suites, run test files containing the word `sample` in their title. | +| `scala3-compiler/Test/runMain dotty.tools.printTypes`| Print types underlying representation | +| `scaladoc/generateScalaDocumentation` | Build the documentation website (published to https://dotty.epfl.ch) | +| `scaladoc/generateReferenceDocumentation` | Build the reference documentation website (published to https://docs.scala-lang.org/scala3/reference) | + + +## Shell Commands + +Below is a cheat sheet of some frequently used commands to be used from your +shell. + +| Command | Description | +|--------------------------------------|------------------------------------------------------------------| +| `rm -rv *.tasty *.class out || true` | clean all compiled artifacts, from root dotty directory | +| `git clean -fdx` | a full clean of all files in the codebase not tracked by git | diff --git a/docs/_docs/contributing/checklist.sh b/docs/_docs/contributing/checklist.sh deleted file mode 100755 index d3cfe70b4e21..000000000000 --- a/docs/_docs/contributing/checklist.sh +++ /dev/null @@ -1,60 +0,0 @@ -# #!/usr/bin/env bash -stable=$1 - -rc="$(($stable+1))" -next="$(($rc+1))" - -stable_version="0.$stable.0" -rc_version="0.$rc.0-RC1" -next_version="0.$next.0" -stable_branch="0.$stable.x" -rc_branch="0.$rc.x" - -LIST='- [ ] Publish artifacts to Maven via CI - - [ ] On branch ``, set `baseVersion` to `` and `git tag` it as ``. This will publish artefacts to Sonatype and GitHub Release - - [ ] Merge branch `` into `master` to guarantee that all of the `` commits are propagated to `master` - - [ ] Look at the milestone of the RC version being released. Move all the open issues from it to the next milestone. - - [ ] Create branch `` from `master` - - [ ] On ``, set `baseVersion` to `` and `git tag` it as ``. This will publish artefacts to Sonatype and GitHub Release. - - [ ] On `master`, set `baseVersion` to `` -- [ ] Update `scalaVersion` (and, if applicable, the `sbt-dotty` version) in the Dotty ecosystem projects - - [ ] https://github.com/scala/scala3-example-project [![Build Status](https://travis-ci.org/scala/scala3-example-project.svg?branch=master)](https://travis-ci.org/scala/scala3-example-project) - - [ ] Committed to `master` - - [ ] https://github.com/scala/scala3-example-project/tree/mill - - [ ] https://github.com/scala/scala3.g8 [![Build Status](https://travis-ci.org/scala/scala3.g8.svg?branch=master)](https://travis-ci.org/scala/scala3.g8/) - - [ ] Committed to `master` - - [ ] https://github.com/scala/scala3-cross.g8 [![Build Status](https://travis-ci.org/scala/scala3-cross.g8.svg?branch=master)](https://travis-ci.org/scala/scala3-cross.g8/) - - [ ] Committed to `master` - - [ ] https://github.com/lampepfl/homebrew-brew [![Build Status](https://travis-ci.org/lampepfl/homebrew-brew.svg?branch=master)](https://travis-ci.org/lampepfl/homebrew-brew) - - [ ] Committed to `master` - - SHA256 sum for the artifact: `wget -q -O- https://github.com/lampepfl/dotty/releases/download//sha256sum.txt | grep ".tar.gz"` - - [ ] https://github.com/lampepfl/packtest [![Build Status](https://travis-ci.org/lampepfl/packtest.svg?branch=master)](https://travis-ci.org/lampepfl/packtest) - - [ ] Committed to `master` - - [ ] https://github.com/lampepfl/xml-interpolator [![Build Status](https://travis-ci.org/lampepfl/xml-interpolator.svg?branch=master)](https://travis-ci.org/lampepfl/xml-interpolator) - - [ ] PR submitted - - [ ] PR merged - - [ ] https://github.com/scalacenter/scastie - - [ ] PR submitted - - [ ] PR merged - - [ ] https://scastie.scala-lang.org/ -> Build Settings -> Dotty mentions `` - - [ ] Dotty reference compiler [![Build Status](http://dotty-ci.epfl.ch/api/badges/lampepfl/dotty/status.svg)](http://dotty-ci.epfl.ch/lampepfl/dotty) - - [ ] PR submitted - - [ ] PR merged - - [ ] Scalac [![Build Status](https://travis-ci.org/scala/scala.svg?branch=2.13.x)](https://travis-ci.org/scala/scala) - - [ ] PR submitted - - [ ] PR merged -- [ ] Announce the release - - [ ] Publish releases for the RC and stable versions on GitHub Releases - - [ ] Publish Blog Post on dotty.epfl.ch - - [ ] Make an announcement thread on https://contributors.scala-lang.org - - [ ] Tweet the announcement blog post on https://twitter.com/scala_lang - - [ ] Run workflow releases CI to publish scala on SDKMAN - https://github.com/lampepfl/dotty/actions/workflows/releases.yml - -[Instructions on how to release](https://dotty.epfl.ch/docs/contributing/release.html)' - -echo "$LIST" |\ - sed "s//$stable_version/g" |\ - sed "s//$rc_version/g" |\ - sed "s//$next_version/g" |\ - sed "s//$stable_branch/g" |\ - sed "s//$rc_branch/g" diff --git a/docs/_docs/contributing/debug-tests.md b/docs/_docs/contributing/debug-tests.md deleted file mode 100644 index a38338fcc745..000000000000 --- a/docs/_docs/contributing/debug-tests.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -layout: doc-page -title: Tests for Debuggability ---- - -## Tools Requires - -- JDB -- expect - -Both are usually pre-installed on macOS and linux distributions. - -## Debug Manually with JDB - -First, compile the file `tests/debug/while.scala`: - -```shell -$ scalac tests/debug/while.scala -``` - -Second, run the compiled class with debugging enabled (suppose the main class is `Test`): - -```shell -$ scala -d Test -``` - -Third, start JDB: - -```shell -$ jdb -attach 5005 -sourcepath tests/debug/ -``` - -You can run `help` for commands that supported by JDB. - -## Debug Automatically with Expect - -### 1. Annotate the source code with debug information. - -Following file (`tests/debug/while.scala`) is an example of annotated source code: - -```scala -object Test { - - def main(args: Array[String]): Unit = { - var a = 1 + 2 - a = a + 3 - a = 4 + 5 // [break] [step: while] - - while (a * 8 < 100) { // [step: a += 1] - a += 1 // [step: while] [cont: print] - } - - print(a) // [break] [cont] - } -} -``` - -The debugging information is annotated as comments to the code in brackets: - -```scala -val x = f(3) // [break] [next: line=5] -val y = 5 -``` - -1. A JDB command must be wrapped in brackets, like `[step]`. All JDB commands can be used. -2. To check output of JDB for a command, use `[cmd: expect]`. -3. If `expect` is wrapped in double quotes, regex is supported. -4. Break commands are collected and set globally. -5. Other commands will be send to jdb in the order they appear in the source file - -Note that JDB uses line number starts from 1. - -### 2. Generate Expect File - -Now we can run the following command to generate an expect file: - -```shell -compiler/test/debug/Gen tests/debug/while.scala > robot -``` - -### 3. Run the Test - -First, compile the file `tests/debug/while.scala`: - -```shell -$ scalac tests/debug/while.scala -``` - -Second, run the compiled class with debugging enabled: - -```shell -$ scala -d Test -``` - -Finally, run the expect script: - -```shell -expect robot -``` - -## Other Tips - -### Adding a New Test - -Just put the annotated source file under `tests/debug/`, it will be automatically -run by the test infrastructure. - -### Run All Debug Tests - -```shell -./compiler/test/debug/test -``` - -### Debug a Debug Test - -If there is any problem with a debug test, first check if the problematic -test work correctly with JDB without automation. - -Then, uncomment the following line in the generated expect file to check the -output of expect: - -``` -# exp_internal 1 -``` diff --git a/docs/_docs/contributing/debugging/debugging.md b/docs/_docs/contributing/debugging/debugging.md new file mode 100644 index 000000000000..3ddbde2244e8 --- /dev/null +++ b/docs/_docs/contributing/debugging/debugging.md @@ -0,0 +1,14 @@ +--- +layout: doc-page +title: Debugging the Compiler +redirectFrom: /docs/contributing/issues/debugging.html +--- + +This section goes over the various ways to debug either the compiler or the code +that you're having issues with. This can be just inspecting the trees of your +code or stepping through the dotty codebase with a Debugger. + +The following sections will help you with this: +- [Debugging with your IDE](./ide-debugging.md.md) +- [How to Inspect Values](./inspection.md) +- [Other Debugging Techniques](./other-debugging.md) diff --git a/docs/_docs/contributing/issues/debugging.md b/docs/_docs/contributing/debugging/ide-debugging.md similarity index 99% rename from docs/_docs/contributing/issues/debugging.md rename to docs/_docs/contributing/debugging/ide-debugging.md index 2d8a9e5941e4..8eaef0594736 100644 --- a/docs/_docs/contributing/issues/debugging.md +++ b/docs/_docs/contributing/debugging/ide-debugging.md @@ -1,6 +1,6 @@ --- layout: doc-page -title: Debugging the Compiler +title: Debugging with your IDE --- The debugger is a powerful tool to navigate the internals of the compiler and track bugs. diff --git a/docs/_docs/contributing/issues/inspection.md b/docs/_docs/contributing/debugging/inspection.md similarity index 95% rename from docs/_docs/contributing/issues/inspection.md rename to docs/_docs/contributing/debugging/inspection.md index abedc09ecd3b..5fae454b9720 100644 --- a/docs/_docs/contributing/issues/inspection.md +++ b/docs/_docs/contributing/debugging/inspection.md @@ -1,6 +1,7 @@ --- layout: doc-page title: How to Inspect Values +redirectFrom: /docs/contributing/issues/inspection.html --- In this section, you will find out how to debug the contents of certain objects @@ -11,7 +12,10 @@ while the compiler is running, and inspect produced artifacts of the compiler. Frequently you will need to inspect the content of a particular variable. You can either use `println`s or the debugger, more info on how to setup the latter. -In the remeainder of this article we'll use `println()` inserted in the code, but the same effect can be accomplished by stopping at a breakpoint, and typing `` in the [debug console](./debugging.md#the-debug-console) of the debugger. +In the remainder of this article we'll use `println()` +inserted in the code, but the same effect can be accomplished by stopping at a +breakpoint, and typing `` in the [debug +console](./ide-debugging.md#the-debug-console) of the debugger. When printing a variable, it's always a good idea to call `show` on that variable: `println(x.show)`. Many objects of the compiler define `show`, returning a human-readable string. @@ -102,6 +106,7 @@ If you are curious about the representation of a type, say `[T] =>> List[T]`, you can use a helper program [dotty.tools.printTypes][DottyTypeStealer], it prints the internal representation of types, along with their class. It can be invoked from the sbt shell with three arguments as follows: + ```bash sbt:scala3> scala3-compiler/Test/runMain dotty.tools.printTypes diff --git a/docs/_docs/contributing/issues/other-debugging.md b/docs/_docs/contributing/debugging/other-debugging.md similarity index 87% rename from docs/_docs/contributing/issues/other-debugging.md rename to docs/_docs/contributing/debugging/other-debugging.md index 1aa0fb85e5f8..50be43db51ab 100644 --- a/docs/_docs/contributing/issues/other-debugging.md +++ b/docs/_docs/contributing/debugging/other-debugging.md @@ -1,39 +1,99 @@ --- layout: doc-page title: Other Debugging Techniques +redirectFrom: /docs/contributing/issues/debugging.html --- -## Setting up the playground -Consider the `../issues/Playground.scala` (relative to the Dotty directory) file is: +## Debug Manually with JDB + +First, compile the file `tests/debug/while.scala`: + +```shell +$ scalac tests/debug/while.scala +``` + +Second, run the compiled class with debugging enabled (suppose the main class is `Test`): + +```shell +$ scala -d Test +``` + +Third, start JDB: + +```shell +$ jdb -attach 5005 -sourcepath tests/debug/ +``` + +You can run `help` for commands that supported by JDB. + +## Debug Automatically with Expect + +### 1. Annotate the source code with debug information. + +Following file (`tests/debug/while.scala`) is an example of annotated source code: ```scala -object Playground { - def main(args: Array[String]) = { - println("Hello World") +object Test { + + def main(args: Array[String]): Unit = { + var a = 1 + 2 + a = a + 3 + a = 4 + 5 // [break] [step: while] + + while (a * 8 < 100) { // [step: a += 1] + a += 1 // [step: while] [cont: print] + } + + print(a) // [break] [cont] } } ``` -Then, you can debug Dotty by compiling this file via `scalac ../issues/Playground.scala` (from the SBT console) and collecting various debug output in process. This section documents techniques you can use to collect the debug info. - -[This](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/typer/Typer.scala#L2231) is the entry point to the Typer. The job of the Typer is to take an untyped tree, compute its type and turn it into a typed tree by attaching the type information to that tree. We will use this entry point to practice debugging techniques. E.g.: +The debugging information is annotated as comments to the code in brackets: ```scala - def typed(tree: untpd.Tree, pt: Type, locked: TypeVars)(implicit ctx: Context): Tree = - trace(i"typing $tree", typr, show = true) { - println("Hello Debug!") - /*...*/ +val x = f(3) // [break] [next: line=5] +val y = 5 +``` + +1. A JDB command must be wrapped in brackets, like `[step]`. All JDB commands can be used. +2. To check output of JDB for a command, use `[cmd: expect]`. +3. If `expect` is wrapped in double quotes, regex is supported. +4. Break commands are collected and set globally. +5. Other commands will be send to jdb in the order they appear in the source file + +Note that JDB uses line number starts from 1. + +### 2. Generate Expect File + +Now we can run the following command to generate an expect file: + +```shell +compiler/test/debug/Gen tests/debug/while.scala > robot ``` -Then: +### 3. Run the Test + +First, compile the file `tests/debug/while.scala`: + +```shell +$ scalac tests/debug/while.scala +``` + +Second, run the compiled class with debugging enabled: ```shell -scalac ../issues/Playground.scala +$ scala -d Test ``` -The techniques discussed below can be tried out in place of `println("Hello Debug")` in that location. They are of course applicable throughout the codebase. +Finally, run the expect script: + +```shell +expect robot +``` +## Other tips +### Show for human readable output -## Show for human readable output Many objects in the compiler have a `show` method available on them via implicit rich wrapper: ```scala @@ -42,7 +102,8 @@ println(tree.show) This will output every single tree passing through the typer (or wherever else you inject it) in a human readable form. Try calling `show` on anything you want to be human-readable, and chances are it will be possible to do so. -## How to disable color +### How to disable color + Note that the `show` command above outputs the code in color. This is achieved by injecting special characters into the strings which terminals interpret as commands to change color of the output. This however may not be what you want, e.g. if you want to zero-in on a particular tree: ```scala @@ -56,7 +117,7 @@ To disable color output from `show`, run `scalac` as follows: `scalac -color:never ../issues/Playground.scala` -## Reporting as a non-intrusive println +### Reporting as a non-intrusive println Consider you want to debug the `tree` that goes into `assertPositioned(tree)` in the `typed` method. You can do: ```scala @@ -72,7 +133,7 @@ assertPositioned(tree.reporting(s"Tree is: $result")) `extension (a: A) def reporting(f: WrappedResult[T] ?=> String, p: Printer = Printers.default): A` is defined on all types. The function `f` can be written without the argument since it is a context function. The `result` variable is a part of the `WrapperResult` โ€“ a tiny framework powering the `reporting` function. Basically, whenever you are using `reporting` on an object `A`, you can use the `result: A` variable from this function and it will be equal to the object you are calling `reporting` on. -## Printing out trees after phases +### Printing out trees after phases To print out the trees you are compiling after the FrontEnd (scanner, parser, namer, typer) phases: ```shell @@ -121,7 +182,7 @@ dotty.tools.dotc.typer.Namer.recur$3$$anonfun$2(Namer.scala:495) So, the error happened in the Namer's `checkNoConflict` method (after which all the stack frames represent the mechanics of issuing an error, not an intent that produced the error in the first place). -## Configuring the printer output +### Configuring the printer output Printing from the `show` and `-Xprint` is done from the Printers framework (discussed in more details below). The following settings influence the output of the printers: ```scala @@ -181,8 +242,8 @@ package @ { @ ``` -## Figuring out an object creation site -### Via ID +### Figuring out an object creation site +#### Via ID Every [Positioned](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/ast/Positioned.scala) (a parent class of `Tree`) object has a `uniqueId` field. It is an integer that is unique for that tree and doesn't change from compile run to compile run. You can output these IDs from any printer (such as the ones used by `.show` and `-Xprint`) via `-Yshow-tree-ids` flag, e.g.: ```shell @@ -284,7 +345,7 @@ So that tree was created at: Since all the stack frames above it are technical frames executing the tree creation command, and the frame in question is the location where the intent of the tree creation was expressed. -### Via tracer +#### Via tracer Some objects may not be `Positioned` and hence their creation site is not debuggable via the technique in the section above. Say you target a tree at `Typer`'s `typed` method as follows: ```scala @@ -309,7 +370,7 @@ if (tree.show == """println("Hello World")""") { } ``` -## Built-in Logging Architecture +### Built-in Logging Architecture Dotty has a lot of debug calls scattered throughout the code, most of which are disabled by default. At least three (possibly intertwined) architectures for logging are used for that: - Printer @@ -318,7 +379,7 @@ Dotty has a lot of debug calls scattered throughout the code, most of which are These do not follow any particular system and so probably it will be easier to go with `println` most of the times instead. -### Printers +#### Printers Defined in [Printers.scala](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/config/Printers.scala) as a set of variables, each responsible for its own domain. To enable them, replace `noPrinter` with `default`. [Example](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/typer/Typer.scala#L2226) from the code: ```scala @@ -327,7 +388,7 @@ typr.println(i"make contextual function $tree / $pt ---> $ifun") `typr` is a printer. -### Tracing +#### Tracing Defined in [trace.scala](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/reporting/trace.scala). [Example](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/typer/Typer.scala#L2232) from the code: ```scala @@ -344,5 +405,5 @@ To enable for a single trace, do the following: trace.force(i"typing $tree", typr, show = true) { // ... ``` -### Reporter +#### Reporter Defined in [Reporter.scala](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/reporting/Reporter.scala). Enables calls such as `report.log`. To enable, run scalac with `-Ylog:typer` option. diff --git a/docs/_docs/contributing/getting-started.md b/docs/_docs/contributing/getting-started.md index af9f2f0783b8..938e7ff36d42 100644 --- a/docs/_docs/contributing/getting-started.md +++ b/docs/_docs/contributing/getting-started.md @@ -1,6 +1,7 @@ --- layout: doc-page title: Getting Started +redirectFrom: /docs/contributing/workflow.html --- ## Scala CLA @@ -25,16 +26,23 @@ never a bad idea to check. - [git] is essential for managing the Scala 3 code, and contributing to GitHub, where the code is hosted. - A Java Virtual Machine (JDK 8 or higher), required for running the build tool. - - download Java from [Oracle Java 8][java8], [Oracle Java 11][java11], - or [AdoptOpenJDK 8/11][adopt]. Refer to [JDK Compatibility][compat] for Scala/Java compatibility detail. + - There are multiple ways to get and manage different Java versions. Some + popular options are: + - [SDKMAN!](https://sdkman.io/) + - [Coursier](https://get-coursier.io/docs/cli-java) + - Or just download Java directly from [Oracle Java 8][java8], [Oracle + Java 11][java11], or [AdoptOpenJDK 8/11][adopt]. Refer to [JDK + Compatibility][compat] for Scala/Java compatibility detail. - Verify that the JVM is installed by running the following command in a terminal: `java -version`. - [sbt][sbt-download], the build tool required to build the Scala 3 compiler and libraries. ## Nice To Have -An IDE, such as [Metals] will help you develop in Scala 3 with features such as autocompletion or goto-definition, -and with the [VS Code][vs-code] text editor you can even use the Scala debugger, or create interactive worksheets for an -iterative workflow. +An IDE, such as [Metals] will help you develop in Scala 3 with features such as +autocompletion, code navigation, debugging, and interactive worksheets. + +Another popular options is [IntelliJ IDEA for +Scala](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html). ## Compiling and Running @@ -43,7 +51,6 @@ Start by cloning the repository: ```bash $ git clone https://github.com/lampepfl/dotty.git $ cd dotty -$ sbt managedSources # Needed for IDE import to succeed ``` Dotty provides a standard sbt build: compiling, running and starting a repl can @@ -56,11 +63,12 @@ $ sbt hello world ``` -There are also bash scripts that can be used in the same way. Assuming that you have cloned the Dotty repo locally, append -the following line on your `.bash_profile`: +There are also bash scripts that can be used in the same way. Assuming that you +have cloned the Dotty repo locally, append the following line on your +`.bash_profile`, or equivalent for your shell: ```shell -$ export PATH=$HOME/dotty/bin:$PATH +$ export PATH=/bin:$PATH ``` and you will be able to run the corresponding commands directly from your console: @@ -73,7 +81,6 @@ $ scalac tests/pos/HelloWorld.scala $ scala HelloWorld ``` - ## Starting a REPL ```bash @@ -109,15 +116,13 @@ where `dotty-version` can be found in the file `project/Build.scala`, like `3.0. ## Generating Documentation To generate this page and other static page docs, run + ```bash $ sbt > scaladoc/generateScalaDocumentation ``` -For more information, see `scaladoc/README.md`. - -Before contributing to Dotty, we invite you to consult the -[Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/main/CONTRIBUTING.md). +For more information, see the [scaladoc section](./scaladoc.md). ## Community diff --git a/docs/_docs/contributing/index.md b/docs/_docs/contributing/index.md index 0cc87e4b3500..507149340941 100644 --- a/docs/_docs/contributing/index.md +++ b/docs/_docs/contributing/index.md @@ -12,16 +12,17 @@ also documents the inner workings of the Scala 3 compiler, `dotc`. Keep in mind that the code for `dotc` is continually changing, so the ideas discussed in this guide may fall out of date. This is a living document, so please consider contributing to it on -[GitHub](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution) -if you notice anything out of date, or report any issues -[here](https://github.com/scala/docs.scala-lang/issues). +[GitHub](https://github.com/lampepfl/dotty/tree/main/docs/_docs/contributing) if +you notice anything out of date, or report any issues +[here](https://github.com/lampepfl/dotty/issues). -### Get the Most from This Guide +### Get the most from This Guide `dotc` is built with Scala 3, fully utilising its [new -features](https://docs.scala-lang.org/scala3/new-in-scala3.html). It is recommended that you first have -some familiarity with Scala 3 to get the most out of this guide. You can learn -more in the [language reference](../reference/overview.md). +features](https://docs.scala-lang.org/scala3/new-in-scala3.html). It is +recommended that you first have some familiarity with Scala 3 to get the most +out of this guide. You can learn more in the [language +reference](../reference/overview.md). Many code snippets in this guide make use of shell commands (a line beginning with `$`), and in this case a `bash` compatible shell is assumed. You may have @@ -39,11 +40,3 @@ another programming language. As an example, `dotc` takes text input, verifies that it is a valid Scala program and then produces as output the same program, but written in Java bytecode, and optionally in SJSIR when producing Scala.js output. - -### Contribute Internals-related Knowledge -If you know anything useful at all about Dotty, feel free to log this knowledge: - -- [๐Ÿ“œLog the Knowledge](https://github.com/lampepfl/dotty-knowledge/issues/new) -- [๐ŸŽ“More about Logging the Knowledge](https://github.com/lampepfl/dotty-knowledge/blob/master/README.md) - -In short, no need to make it pretty, particularly human-readable or give it a particular structure. Just dump the knowledge you have and we'll take it from there. \ No newline at end of file diff --git a/docs/_docs/contributing/issues/cause.md b/docs/_docs/contributing/issues/cause.md index 5bb04e894f70..10c29dc0c398 100644 --- a/docs/_docs/contributing/issues/cause.md +++ b/docs/_docs/contributing/issues/cause.md @@ -9,12 +9,13 @@ In this section, you will be able to answer questions such as: - where is a particular object created? - where is a particular value assigned to a variable? -> You may be able to quickly find the source responsible for an issue by consulting [common issue locations](../issues/areas.md) +> You may be able to quickly find the source responsible for an issue by consulting [common issue locations](./areas.md) ## What phase generated a particular tree? -As described in the [compiler lifecycle](../architecture/lifecycle.md#phases), each phase transforms the trees -and types that represent your code in a certain way. +As described in the [compiler lifecycle](../architecture/lifecycle.md#phases-2), +each phase transforms the trees and types that represent your code in a certain +way. To print the code as it is transformed through the compiler, use the compiler flag `-Xprint:all`. After each phase group is completed, you will see the resulting trees representing the code. @@ -61,9 +62,10 @@ To discover why such a *spurious* error is generated, you can trace the code tha adding the `-Ydebug-error` compiler flag, e.g. `scala3/scalac -Ydebug-error Test.scala`. This flag forces a stack trace to be printed each time an error happens, from the site where it occurred. -Analysing the trace will give you a clue about the objects involved in producing the error. -For example, you can add some debug statements before the error is issued to discover -the state of the compiler. [See some useful ways to debug values.](./inspection.md) +Analysing the trace will give you a clue about the objects involved in producing +the error. For example, you can add some debug statements before the error is +issued to discover the state of the compiler. [See some useful ways to debug +values.](./debugging/inspection.md) ### Where was a particular object created? @@ -73,6 +75,7 @@ creation site of that object to understand the logic that created it. You can do this by injecting a *tracer* into the class of an instance in question. A tracer is the following variable: + ```scala val tracer = Thread.currentThread.getStackTrace.mkString("\n") ``` diff --git a/docs/_docs/contributing/issues/diagnosing-your-issue.md b/docs/_docs/contributing/issues/diagnosing-your-issue.md new file mode 100644 index 000000000000..d6f2e675c1a3 --- /dev/null +++ b/docs/_docs/contributing/issues/diagnosing-your-issue.md @@ -0,0 +1,17 @@ +--- +layout: doc-page +title: Diagnosing your issue +--- + +This section is meant to help you diagnose and reproduce what the actual issue +is that you're trying to fix. Firstly, you'll need to reproduce the issue, so +that + +- you can understand its cause +- you can verify that any changes made to the codebase have a positive impact on the issue. + +The following sections will help you out with this: + +- [Reproducing an Issue](./reproduce.md) +- [Finding the Cause of an Issue](./cause.md) +- [Common issue locations](./areas.md) diff --git a/docs/_docs/contributing/issues/efficiency.md b/docs/_docs/contributing/issues/efficiency.md deleted file mode 100644 index 07307646a4bb..000000000000 --- a/docs/_docs/contributing/issues/efficiency.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: doc-page -title: Improving Your Workflow ---- - -In the previous sections of this chapter, you saw some techniques for -working with the compiler. Some of these techniques can be used -repetitively, e.g.: - -- Navigating stack frames -- Printing variables in certain ways -- Instrumenting variable definitions with tracers - -The above procedures often take a lot of time when done manually, reducing productivity: -as the cost (in terms of time and effort) is high, you may avoid attempting to do so, -and possibly miss valuable information. - -If you're doing those things really frequently, it is recommended to script your editor -to reduce the number of steps. E.g. navigating to the definition of a stack frame -part when you click it, or instrumenting variables for printing. - -An example of how it is done for Sublime Text 3 is [here](https://github.com/anatoliykmetyuk/scala-debug-sublime). - -True, it takes some time to script your editor, but if you spend a lot of time with issues, it pays off. diff --git a/docs/_docs/contributing/issues/index.md b/docs/_docs/contributing/issues/index.md deleted file mode 100644 index db348d7edd9d..000000000000 --- a/docs/_docs/contributing/issues/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: index -title: Finding the Cause of an Issue ---- - -An issue found in the [GitHub repo][lampepfl/dotty] usually describes some code that -manifests undesired behaviour. - -This chapter of the guide describes the different steps to contribute to Dotty: -- [Reproducing an Issue](./reproduce.md) -- [Finding the Cause of an Issue](./cause.md) -- [Debugging the Compiler](./debugging.md) -- [Other debugging techniques](./other-debugging.md) -- [Inspect the values](./inspection.md) -- [Improving your workflow](./efficiency.md) -- [Testing a Fix](./testing.md) -- [Checklist](./checklist.md) diff --git a/docs/_docs/contributing/issues/reproduce.md b/docs/_docs/contributing/issues/reproduce.md index 41d96327ef24..3d15d4bfb6ec 100644 --- a/docs/_docs/contributing/issues/reproduce.md +++ b/docs/_docs/contributing/issues/reproduce.md @@ -3,22 +3,58 @@ layout: doc-page title: Reproducing an Issue --- -To try fixing it, you will first need to reproduce the issue, so that -- you can understand its cause -- you can verify that any changes made to the codebase have a positive impact on the issue. +The first step is to reproduce the issue you're trying to fix. Say you want to +reproduce locally issue [#7710], you would first copy the code from the +*"Minimised Code"* section of the issue to a file named e.g. +`local/i7710.scala`, and then try to compile it from the sbt console opened in +the dotty root directory: -Say you want to reproduce locally issue [#7710], you would first copy the code from the *"Minimised Code"* -section of the issue to a file named e.g. `local/i7710.scala`, -and then try to compile it from the sbt console opened in the dotty root directory: ```bash $ sbt -sbt:scala3> scala3/scalac -d local/out local/i7710.scala +sbt:scala3> scalac -d local/out local/i7710.scala ``` > Here, the `-d` flag specifies a directory `local/out` where generated code will be output. -You can then verify that the local reproduction has the same behaviour as originally reported in the issue. -If so, then you can start to try and fix it. Otherwise, perhaps the issue is out of date, or -is missing information about how to accurately reproduce the issue. +You can then verify that the local reproduction has the same behaviour as +originally reported in the issue. If so, then you can start to try and fix it. +Otherwise, perhaps the issue is out of date, or is missing information about how +to accurately reproduce the issue. + +## Compiling files with scalac + +Let's take a deeper look at this `scalac` command we just used. As we have seen +you can compile a test file either from sbt: + +```bash +$ sbt +> scalac +``` + +in the same way that you could from terminal: + +```bash +$ scalac +``` + +Here are some useful debugging ``: + +* `-Xprint:PHASE1,PHASE2,...` or `-Xprint:all`: prints the `AST` after each + specified phase. Phase names can be found by examining the + `dotty.tools.dotc.transform.*` classes for their `phaseName` field e.g., `-Xprint:erasure`. + You can discover all phases in the `dotty.tools.dotc.Compiler` class +* `-Ylog:PHASE1,PHASE2,...` or `-Ylog:all`: enables `ctx.log("")` logging for + the specified phase. +* `-Ycheck:all` verifies the consistency of `AST` nodes between phases, in + particular checks that types do not change. Some phases currently can't be + `Ycheck`ed, therefore in the tests we run: + `-Ycheck:tailrec,resolveSuper,mixin,restoreScopes,labelDef`. +* the last frontier of debugging (before actual debugging) is the range of logging capabilities that +can be enabled through the `dotty.tools.dotc.config.Printers` object. Change any of the desired printer from `noPrinter` to +`default` and this will give you the full logging capability of the compiler. + +You may also want to further inspect the types of a piece of code to verify the +AST. Check out the section on [How to Inspect +Values](../debugging/inspection.md) for a detailed guide on this. ## Dotty Issue Workspace @@ -85,24 +121,25 @@ the dollar notation: `$1` for the first argument, `$2` for the second and so on. ### Multiline Commands -Inside a `launch.iss` file, one command can be spread accross multiple lines. For example, +Inside a `launch.iss` file, one command can be spread across multiple lines. For example, if your command has multiple arguments, you can put each argument on a new line. -Multiline commands can even have comments inbetween lines. This is useful +Multiline commands can even have comments in-between lines. This is useful if you want to try variants of a command with optional arguments (such as configuration). You can put the optional arguments on separate lines, and then decide when they are passed to the command by placing `#` in front to convert it to a comment (i.e. the argument will not be passed). This saves typing the same arguments each time you want to use them. -The following `launch.iss` file is an example of how you can use multiline commands as a -template for solving issues that [run compiled code](../issues/testing.md#checking-program-output). It demonstrates configuring the -`scala3/scalac` command using compiler flags, which are commented out. -Put your favourite flags there for quick usage. +The following `launch.iss` file is an example of how you can use multiline +commands as a template for solving issues that [run compiled +code](../issues/testing.md#checking-program-output). It demonstrates configuring +the `scala3/scalac` command using compiler flags, which are commented out. Put +your favourite flags there for quick usage. ```bash $ (rm -rv out || true) && mkdir out # clean up compiler output, create `out` dir. -scala3/scalac # Invoke the compiler task defined by the Dotty sbt project +scalac # Invoke the compiler task defined by the Dotty sbt project -d $here/out # All the artefacts go to the `out` folder created earlier # -Xprint:typer # Useful debug flags, commented out and ready for quick usage. Should you need one, you can quickly access it by uncommenting it. # -Ydebug-error @@ -113,7 +150,7 @@ scala3/scalac # Invoke the compiler task defined by the Dotty sbt project # -Ycheck:all $here/$1.scala # Invoke the compiler on the file passed as the second argument to the `issue` command. E.g. `issue foo Hello` will compile `Hello.scala` assuming the issue folder name is `foo`. -scala3/scala -classpath $here/out Test # Run main method of `Test` generated by the compiler run. +scala -classpath $here/out Test # Run main method of `Test` generated by the compiler run. ``` ## Conclusion @@ -124,4 +161,4 @@ how to try and detect its root cause. [lampepfl/dotty]: https://github.com/lampepfl/dotty/issues [#7710]: https://github.com/lampepfl/dotty/issues/7710 [dotty-issue-workspace]: https://github.com/anatoliykmetyuk/dotty-issue-workspace -[workspace-readme]: https://github.com/anatoliykmetyuk/dotty-issue-workspace#getting-started \ No newline at end of file +[workspace-readme]: https://github.com/anatoliykmetyuk/dotty-issue-workspace#getting-started diff --git a/docs/_docs/contributing/procedures/index.md b/docs/_docs/contributing/procedures/index.md index db2b09dbe80f..c614a0a88fd4 100644 --- a/docs/_docs/contributing/procedures/index.md +++ b/docs/_docs/contributing/procedures/index.md @@ -4,5 +4,4 @@ title: Procedures --- This chapter of the guide describes: -- [How to release a procedure](./release.md) -- [How to test the vulpix framework](./vulpix.md) \ No newline at end of file +- [How to test the vulpix framework](./vulpix.md) diff --git a/docs/_docs/contributing/procedures/release.md b/docs/_docs/contributing/procedures/release.md index 8f66f8854d4c..c54bb637aff5 100644 --- a/docs/_docs/contributing/procedures/release.md +++ b/docs/_docs/contributing/procedures/release.md @@ -4,7 +4,7 @@ title: Release Procedure --- # Model -The easiest way to produce a release of a GitHub-based open-source software is to tag the most recent commit on the `master` with the version number at regular intervals of time or once a previously agreed milestone is reached. However, this approach to releasing would rest on the assumption that each commit at the `master` branch can potentially be made into a release. We cannot provide the release-grade quality guarantees for each of the `master` commits, though. +The easiest way to produce a release of a GitHub-based open-source software is to tag the most recent commit on the `main` with the version number at regular intervals of time or once a previously agreed milestone is reached. However, this approach to releasing would rest on the assumption that each commit at the `main` branch can potentially be made into a release. We cannot provide the release-grade quality guarantees for each of the `main` commits, though. Consequently, in Dotty, we are using the method above โ€“ releasing-by-tagging โ€“ to mark release candidates (RCโ€™s) and not the stable releases. The stable releases are also marked by a tag, but we have a procedure to assure their quality. @@ -16,12 +16,12 @@ If such issues are found, their fixes end up on a separate branch dedicated to t Say we want to release the 0.14.0 version. In this section we describe the process to do so (at a glance). ## At the Dotty Repo -1. Tag the latest `master` commit as `0.14.0-RC1`. This commit is the release candidate for the `0.14.0` version. +1. Tag the latest `main` commit as `0.14.0-RC1`. This commit is the release candidate for the `0.14.0` version. 2. Create a branch from that commit called `0.14.x`. This branch is intended to host the subsequent fixes to the RC for the issues that cannot be allowed in the `0.14.0` stable release. 3. Up until the next release date, if we find some issues with `0.14.0-RC1` that cannot end up in the release, we push the fixes to the `0.14.x` branch. 4. At the next release date, we release `0.14.0` from the branch `0.14.x`. We do so by tagging the latest commit at the `0.14.x` branch as `0.14.0`. Some things to note here: - 1. At this point, `0.14.x` (the branch) and `0.14.0-RC1` (the tag at which `0.14.x` branched from `master`) may differ, and the `0.14.x` branch is a more mature version of the `0.14.0-RC1` tag. - 2. `0.14.0` is not the same as the `master`. Only the commits critical for the `0.14.0` release end up at `0.14.x` branch. Not all of the commits made to the `master` during the release cycle are critical to `0.14.0`. However, all of the commits from `0.14.x` must end up on the `master` branch, so we merge `0.14.x` into `master`. + 1. At this point, `0.14.x` (the branch) and `0.14.0-RC1` (the tag at which `0.14.x` branched from `main`) may differ, and the `0.14.x` branch is a more mature version of the `0.14.0-RC1` tag. + 2. `0.14.0` is not the same as the `main`. Only the commits critical for the `0.14.0` release end up at `0.14.x` branch. Not all of the commits made to the `main` during the release cycle are critical to `0.14.0`. However, all of the commits from `0.14.x` must end up on the `main` branch, so we merge `0.14.x` into `main`. 5. After the `0.14.0` version is released, we start the process for releasing `0.15.0` โ€“ repeat this algorithm from the beginning with the version set to `0.15.0-RC1` at step (1). ## At the CI @@ -37,24 +37,24 @@ The CI operation is entirely automatic provided you have tagged the release corr Note that after the first stage of the release cycle (see "Publishing artifacts to Maven via CI" section of the checklist below) only three test runs are required to be run at the CI: -- `master` branch's latest *commit* with the updated `baseVersion` +- `main` branch's latest *commit* with the updated `baseVersion` - `` *tag* of the stable version being released - `` *tag* of the RC version being released However, you may end up with as many as 6 tasks being run. The auxiliary tasks may include: - *commit* tests of the *tags* specified above. You may have two of these, corresponding to the two tags. You should see them appearing to have the same commit hash in the CI, but one of them will have the tag next to it and the other one will not. The *tag* one must remain, as the CI tasks on tags publish to maven. CI tasks on commits do not. So it is safe to cancel the task running on the commit, if the commit hash is the same as that of the tag's task commit. -- Older commit from the `master` branch. Look for all the tasks run on the `master` branch in the CI and see if there are more than one of these. Then, find the one testing the most recent commit of the branch. The others can safely be canceled. +- Older commit from the `main` branch. Look for all the tasks run on the `main` branch in the CI and see if there are more than one of these. Then, find the one testing the most recent commit of the branch. The others can safely be canceled. ## Documentation ### Release Procedure Checklist Before we start the release procedure, we create an issue with a release checklist. As we go through the release, we update the checklist. To generate the checklist, run the following command: -`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/master/docs/docs/contributing/checklist.sh) ` +`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/main/docs/docs/contributing/checklist.sh) ` Above, `` is the stable version being released. For example, if you are releasing `0.14.0` and `0.15.0-RC1`, this variable is `14` and the command is as follows: -`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/master/docs/docs/contributing/checklist.sh) 14` +`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/main/docs/docs/contributing/checklist.sh) 14` Copy and paste the output into the release issue. @@ -65,49 +65,15 @@ When no criteria is specified, common sense is to be used. ### GitHub Releases and Blog Post After the release is done, we document it as follows: -- On the GitHub release page, modify the release drafts created by CI. The RC draft should include notable changes introduced since the previous RC. E.g. for `0.14.0-RC1` these are generated by `gren changelog -G --override -D prs --tags=0.13.0-RC1..0.14.0-RC1`. `gren` is available [here](https://github.com/github-tools/github-release-notes), and before running the above command, please make sure that (1) the `origin` branch points to the `lampepfl/dotty` repository and (2) the two tags mentioned in the command are pushed to the `master` branch of that repo. Otherwise, the command won't pick up the tags. +- On the GitHub release page, modify the release drafts created by CI. The RC draft should include notable changes introduced since the previous RC. E.g. for `0.14.0-RC1` these are generated by `gren changelog -G --override -D prs --tags=0.13.0-RC1..0.14.0-RC1`. `gren` is available [here](https://github.com/github-tools/github-release-notes), and before running the above command, please make sure that (1) the `origin` branch points to the `lampepfl/dotty` repository and (2) the two tags mentioned in the command are pushed to the `main` branch of that repo. Otherwise, the command won't pick up the tags. - Create a blog article documenting the most important changes done by the release. ## Ecosystem -After releasing a new version of Dotty, we need to make sure to update the following related projects: - -- [Example Project](https://github.com/scala/scala3-example-project) - - To deploy locally: `git clone https://github.com/scala/scala3-example-project.git && cd dotty-example-project/` - - To test locally: `sbt run` - - [Commit](https://github.com/scala/scala3-example-project/commit/76bf0b4d708206b1901fa7f291f07cd470506e79) updating the Dotty version (only `README` and `build.sbt` files) -- [Example Project with Mill](https://github.com/scala/scala3-example-project/tree/mill) - - Deploy: `git clone https://github.com/scala/scala3-example-project && cd dotty-example-project && git checkout mill` - - Test: `mill root.run` - - [Commit 1](https://github.com/scala/scala3-example-project/commit/e1ad1905ef38d07943e0c176333ba24e306a2078) โ€“ `build.sc` only; [Commit 2](https://github.com/scala/scala3-example-project/commit/23bc5df89e72b782ab8e19157d6bbcb67eef30cd) -- [Dotty G8 template](https://github.com/scala/scala3.g8) - - Deploy: `git clone https://github.com/scala/scala3.g8.git` - - Test (note the relative path as argument to `sbt new`, hence this command should be run after Deploy in the same directory as Deploy): `sbt new file://./dotty.g8 --name=foo --description=bar && cd foo && sbt run` - - [Commit](https://github.com/scala/scala3.g8/commit/0cde8fa843e15e916f07f22a196f35a5988b26af) -- [Dotty G8 template with cross build support](https://github.com/scala/scala3-cross.g8) - - Deploy: `git clone https://github.com/scala/scala3-cross.g8.git` - - Test: `sbt new file://./dotty-cross.g8 --name=foo --description=bar && cd foo && sbt run` - - [Commit](https://github.com/scala/scala3-cross.g8/commit/0e3ea2ae8ba8d001e63e5098ff60d728036d358f) -- [Dotty Homebrew Formula](https://github.com/lampepfl/homebrew-brew) - - Deploy: `git clone https://github.com/lampepfl/homebrew-brew.git && cd homebrew-brew` - - [Commit](https://github.com/lampepfl/homebrew-brew/commit/04f7284564387754a360a354159f2f8d6156a6c7). SHA256 sum comes from the issue checklist computed for the release as specified above. The file with checksums is available at [GitHub Releases](https://github.com/lampepfl/dotty/releases) -> release in question -> assets -> `sha256sum.txt` -> `*.tar.gz` file sum. -- [Dotty test under various OSs](https://github.com/lampepfl/packtest) - - Deploy: `git clone https://github.com/lampepfl/packtest.git && cd packtest` - - [Commit](https://github.com/lampepfl/packtest/commit/6d3edf7333e0e788af7c4f4ab976b56905ddf9ed) -- [Scastie](https://github.com/scalacenter/scastie/) - - Deploy (copy-paste the command and append the release id, e.g. `15` for `0.15.0-RC1`): `git clone https://github.com/scalacenter/scastie.git && cd scastie && git remote add staging https://github.com/dotty-staging/scastie && git checkout -b dotty-release-` - - [PR](https://github.com/scalacenter/scastie/pull/433) โ€“ push your changes to `staging` repo (as defined in "Deploy" above) with `git push -u staging`, then submit the PR from there. -- [Dotty](https://github.com/lampepfl/dotty/) - - If you are reading this, Dotty should already be deployed on your machine :) - - [PR](https://github.com/lampepfl/dotty/pull/6557) -- [Scalac](https://github.com/scala/scala) - - Deploy: `git clone https://github.com/scala/scala.git && cd scala && git remote add staging https://github.com/dotty-staging/scala && git checkout -b dotty-release-` - - [PR](https://github.com/scala/scala/pull/7993) - -For each need to do the following: - -- Update Dotty version to the latest RC -- Update the sbt-dotty SBT plugin version to the latest published one -- Update the projects' source code to follow the Dotty developments if necessary + +During the release process we ensure that various parts of the community are +also prepared for the new version of Scala so that users can hit the ground +running when the new release is announced. You can see an example of this +[here](https://github.com/lampepfl/dotty/issues/17559). # Procedure in Bash Scripts The below procedure is compiled from [this](https://github.com/lampepfl/dotty/issues/5907#issue-409313505) and [this](https://github.com/lampepfl/dotty/issues/6235#issue-429265748) checklists. It assumes we want to publish the `0.14.0` given the `0.14.0-RC1` release candidate. @@ -128,11 +94,11 @@ git commit -am 'Release Dotty 0.14.0' git tag 0.14.0 git push origin 0.14.0 -git checkout master +git checkout main git merge 0.14.x # Make sure the merge doesn't break anything. In doubt, create a PR to run the CL -git push origin master +git push origin main ######## Publish the 0.15.0-RC1 unstable version โ€“ begin the release cycle for 0.15.0 ######## # Move all the unfinished tasks from Milestone 15 to Milestone 16 on GitHub โ€“ see https://github.com/lampepfl/dotty/milestones @@ -146,10 +112,10 @@ git tag 0.15.0-RC1 git push origin 0.15.x git push origin 0.15.0-RC1 -git checkout master +git checkout main # Change val baseVersion = "0.15.0" to val baseVersion = "0.16.0" - this will be the next version after `0.15.0-RC1` is promoted to `0.15.0`. git commit -am 'Set baseVersion to 0.16.0' -git push origin master -``` \ No newline at end of file +git push origin main +``` diff --git a/docs/_docs/contributing/scala2-vs-scala3.md b/docs/_docs/contributing/scala2-vs-scala3.md deleted file mode 100644 index b92cbe2381ea..000000000000 --- a/docs/_docs/contributing/scala2-vs-scala3.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: doc-page -title: Divergences between Scala 2 and Dotty ---- - -# Divergences between Scala 2 and Dotty -The following issues encountered when compiling Scala 2 code as-is under Dotty: - -## Scalafix candidates -- If a method is defined `toSet()`, it cannot be called `toSet`. -- โ€œresult type of implicit definition needs to be given explicitlyโ€ -- There are no `'Symbol`s in Scala 3, you must construct symbols via `new Symbol("foo")` instead of old `'foo` - -## Trivial -- Scala 2.13 libraries cannot be used from Dotty because the dotty-library is compiled against the 2.12 standard library which is not binary-compatible with the 2.13 one. We can't be compatible with both at the same time. -- To use Scala 2.12 dependencies from SBT with Dotty, use `withDottyCompat` as documented [here](https://github.com/scala/scala3-example-project#getting-your-project-to-compile-with-dotty). -- Feature warnings about implicits `scala.language.implicitConversions` are output by default, unlike in Scala 2. This creates noise. Unclear how to turn off. - -Implicit conversions must be applied explicitly: - -```scala -implicit def IterablePath[T](s: Iterable[T])(implicit conv: T => RelPath): RelPath = { - s.foldLeft(rel){_ / conv(_)} -} -``` - -Stronger compile time guarantees on variance. Scala 2 does not assert variance on default parameters to parameters of the function value type. E.g. in geny: - -```scala -# Dotty -def count(f: A => Boolean = (a: A) => true): Int = -| ^^^^^^^^^^^^^^ -|covariant type A occurs in contravariant position in type => A => Boolean of method count$default$1 -``` - -Fix: -```scala -# Dotty -def count[B >: A](f: B => Boolean = (_: B) => true): Int = -``` - -## Tricky -- Scala 3 macros are completely different from Scala 2 ones, requires a migration strategy of its own diff --git a/docs/_docs/contributing/scaladoc.md b/docs/_docs/contributing/scaladoc.md new file mode 100644 index 000000000000..be2a14091d00 --- /dev/null +++ b/docs/_docs/contributing/scaladoc.md @@ -0,0 +1,151 @@ +--- +layout: doc-page +title: Scaladoc +--- + +Scaladoc is the documentation tool for [Scala +3](https://github.com/lampepfl/dotty). It uses the TastyInspector to access +definitions, which is an officially supported way to access Scala 3's +perspective of a codebase. + +We're aiming to support all the features Scaladoc did, plus new and exciting ones such as: + +- Markdown syntax! +- displaying project and API documentation together on one site! +- and more! + +**Yes, this page was generated using scaladoc** + +## Running the project + +Use the following commands to generate documentation for this project and for Dotty, respectively: + +``` +sbt scaladoc/generateSelfDocumentation +sbt scaladoc/generateScalaDocumentation +``` + +To actually view the documentation, the easiest way is to run the following in the project root: + +``` +cd scaladoc/output +python3 -m http.server 8080 +``` + +And afterwards point your browser to or + for this project and for Dotty documentation +respectively. + +It's not strictly necessary to go through an HTTP server, but because of CORS +the documentation won't work completely if you don't. + +## CLI and sbt Documentation + +The preferred way to use scaladoc is calling it from sbt `Compile/doc` task or to use CLI interface provided inside `dotty/bin/scaladoc` bash script. +More information about specific scaladoc flags you can find inside [Usage docs](https://docs.scala-lang.org/scala3/guides/scaladoc/settings.html) + +## Developing + +For every PR named with prefix `scaladoc/`, we build documentation for scaladoc and Dotty. For example, for +PR `scaladoc/update-docs` you can find them at: + +- +- +- + +Note that these correspond to the contents of `output` directory - that's +precisely what they are. + +You can also find the result of building the same sites for latest `master` at: + +- +- +- + +### Testing + +Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation +to signatures found in source files. Such tests are defined using [SignatureTest](test/dotty/tools/scaladoc/signatures/SignatureTest.scala) class +and its subtypes (such as [TranslatableSignaturesTestCases](test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala)) + +WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date. +In case of any discrepancies rely on the source files instead. + +`SignatureTest` requires that you specify the names of the files used to extract signatures, +the names of directories containing corresponding TASTY files +and the kinds of signatures from source files (corresponding to keywords used to declare them like `def`, `class`, `object` etc.) +whose presence in the generated documentation will be checked (other signatures, when missing, will be ignored). +The mentioned source files should be located directly inside [](../scaladoc-testcases/src/tests) directory +but the file names passed as parameters should contain neither this path prefix nor `.scala` suffix. + +By default it's expected that all signatures from the source files will be present in the documentation +but not vice versa (because the documentation can contain also inherited signatures). +To validate that a signature present in the source does not exist in the documentation +(because they should be hidden from users) add `//unexpected` comment after the signature in the same line. +This will cause an error if a signature with the same name appears in the documentation +(even if some elements of the signature are slightly different - to avoid accidentally passing tests). +If the signature in the documentation is expected to slightly differ from how it's defined in the source code +you can add a `//expected: ` comment (also in the same line and followed by a space) followed by the expected signature. +Alternatively you can use `/*<-*/` and `/*->*/` as opening and closing parentheses for parts of a signature present in the source but undesired in the documentation (at least at the current stage of development), e.g. + +```scala +def foo/*<-*/()/*->*/: Int +``` + +will make the expected signature be + +```scala +def foo: Int +``` + +instead of + +```scala +def foo(): Int +``` + +Because of the way how signatures in source are parsed, they're expected to span +until the end of a line (including comments except those special ones mentioned +above, which change the behaviour of tests) so if a definition contains an +implementation, it should be placed in a separate line, e.g. + +```scala +def foo: Int + = 1 + +class Bar +{ + //... +} +``` + +Otherwise the implementation would be treated as a part of the signature. + +## Contributing + +We're happy that you'd like to help us! + +We have two issue labels you should take a look at: `good first issue` and +`self-contained`. First is easy pickings: you'll be able to contribute without +needing to dive too deep into the project. Second is reverse: it's an issue +that's you may find interesting, complex and self-contained enough that you can +continue chipping away at it without needing to worry too much about merge +conflicts. + +To contribute to the project with your code, fork this repo and create a pull request from a fresh branch from there. +To keep the history of commits clean, make sure your commits are squashed into one +and all your changes are applied on top of the latest master branch (if not - rebase on it instead of merging it). +Make sure all the tests pass (simply run `sbt test` to verify that). + +## FAQ + + +### Why use TASTy? + +A documentation tool needs to access compiler information about the project - it +needs to list all definitions, resolve them by name, and query their members. +Tasty Reflect is the dedicated way in Scala 3 of accessing this information. + +## Credits + +- [Flatart](https://www.iconfinder.com/Flatart) - Gitter icon diff --git a/docs/_docs/contributing/issues/checklist.md b/docs/_docs/contributing/sending-in-a-pr.md similarity index 98% rename from docs/_docs/contributing/issues/checklist.md rename to docs/_docs/contributing/sending-in-a-pr.md index e2fcf32531de..543073ab86eb 100644 --- a/docs/_docs/contributing/issues/checklist.md +++ b/docs/_docs/contributing/sending-in-a-pr.md @@ -1,6 +1,7 @@ --- layout: doc-page -title: Pull Request Checklist +title: Sending in a pull request +redirectFrom: /docs/contributing/issues/checklist.html --- Once you solved the issue you were working on, you'll likely want to see your diff --git a/docs/_docs/contributing/setting-up-your-ide.md b/docs/_docs/contributing/setting-up-your-ide.md new file mode 100644 index 000000000000..327fa3d1a400 --- /dev/null +++ b/docs/_docs/contributing/setting-up-your-ide.md @@ -0,0 +1,48 @@ +--- +layout: doc-page +title: Setting up your IDE +--- + +You can use either Metals with your favorite editor (VS Code, Neovim, Sublime) +or [IntelliJ IDEA for +Scala](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) +to work on the Scala 3 codebase. There are however a few additional +considerations to take into account. + +## Bootstrapping Projects + +The sbt build for dotty implements bootstrapping within the same build, so each component has +two projects: + +``` +sbt:scala3> projects +... +[info] scala3-compiler +[info] scala3-compiler-bootstrapped +... +``` + +These duplicated projects can be confusing and cause issues in IDEs. + +### Metals + +When using Metals, the `-bootstrapped` projects are not exported by default. +Normally this is fine, but if you're working on certain modules like `scaladoc` +you'll actually want these modules exported. In order to achieve this you'll +first want to ensure you're using `sbt` as your build server instead of the +default Bloop. You can achieve this with the `Metals: Switch Build Server` +command and then choosing sbt. Once you do this, you'll want to find and change +the following under `commonBootstrappedSettings` which is found in the +[`Build.scala`](https://github.com/lampepfl/dotty/blob/main/project/Build.scala) +file. + +```diff + +- bspEnabled := false, ++ bspEnabled := true, +``` + +### IntelliJ + +In IntelliJ IDEA, we recommend importing the dotty codebase through BSP, then +the `-bootstrapped` projects are not exported. diff --git a/docs/_docs/contributing/issues/testing.md b/docs/_docs/contributing/testing.md similarity index 98% rename from docs/_docs/contributing/issues/testing.md rename to docs/_docs/contributing/testing.md index 1f7c35c6d58a..0e30f86608fe 100644 --- a/docs/_docs/contributing/issues/testing.md +++ b/docs/_docs/contributing/testing.md @@ -1,6 +1,7 @@ --- layout: doc-page title: Testing Your Changes +redirectFrom: /docs/contributing/issues/testing.html --- It is important to add tests before a pull request, to verify that everything is working as expected, @@ -50,7 +51,7 @@ or be within a directory called `i101/` for a multi-file test. To run the test, invoke the sbt command `testCompilation i101` (this will match all tests with `"i101"` in the name, so it is useful to use a unique name) -The test groups โ€“ `pos`, `neg`, etc. โ€“ are defined in [CompilationTests]. If you want to run a group +The test groups โ€“ `pos`, `negAll`, etc. โ€“ are defined in [CompilationTests]. If you want to run a group of tests, e.g. `pos`, you can do so via `testOnly *CompilationTests -- *pos` command. ### Testing a Single Input File diff --git a/docs/_docs/contributing/tools/ide.md b/docs/_docs/contributing/tools/ide.md deleted file mode 100644 index 5db333bee9d9..000000000000 --- a/docs/_docs/contributing/tools/ide.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: doc-page -title: Using an IDE ---- - -You can use either Metals (VS Code, vim) or IntelliJ IDEA as described on the -IDE sections of the [getting-started page](https://docs.scala-lang.org/scala3/getting-started.html) to work -on the Scala 3 codebase. There are however a few additional considerations to take into account. - - -## Bootstrapping Projects - -The sbt build for dotty implements bootstrapping within the same build, so each component has -two projects: - -``` -sbt:scala3> projects -... -[info] scala3-compiler -[info] scala3-compiler-bootstrapped -... -``` - -These duplicated projects can be confusing and cause issues in IDEs. - -When using Metals, the `-bootstrapped` projects are not exported. - -In IntelliJ IDEA, we recommend importing the dotty codebase through BSP, then the `-bootstrapped` -projects are not exported. - - -## Scala Version warning in Metals - -When using VS Code, Metals might show a warning that the Scala version (`3.0.0-[...]-NIGHTLY`) -is not supported. The reason is that the dotty repository sometimes uses a nightly build as -reference compiler. The IDE experience is going to be limited in this case (semantic features will -only within single files). diff --git a/docs/_docs/contributing/tools/index.md b/docs/_docs/contributing/tools/index.md deleted file mode 100644 index e784e3e15d61..000000000000 --- a/docs/_docs/contributing/tools/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: index -title: IDEs and Tools ---- - -This chapter of the guide describes how to use Dotty with IDEs and other tools: -- [IDEs](./ide.md) -- [Use Mill](./mill.md) -- [Use Scalafix](./scalafix.md) diff --git a/docs/_docs/contributing/tools/mill.md b/docs/_docs/contributing/tools/mill.md deleted file mode 100644 index 7d372835395f..000000000000 --- a/docs/_docs/contributing/tools/mill.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: doc-page -title: Basic Operations with Mill ---- - -Here's an example of how to test a project that uses mill: - -```bash -mill utest.jvm[2.12.8].test -``` - -- `utest.jvm` - the name of the compiled module (obtain from `build.sc`) -- `2.12.8` โ€“ Scala cross-compile version -- `test` โ€“ task to run on the module specified with the specified Scala version - -To get mill of the most recent version, first, find it in https://github.com/lihaoyi/mill/releases (e.g. `0.4.2-1-020e28`). Copy the download link and substitute it in the following command instead of `https://github.com/lihaoyi/mill/releases/download/0.4.1/0.4.1`: - -```bash -# From http://www.lihaoyi.com/mill/ -sudo sh -c '(echo "#!/usr/bin/env sh" && curl -L https://github.com/lihaoyi/mill/releases/download/0.4.1/0.4.1) > /usr/local/bin/mill && chmod +x /usr/local/bin/mill' -``` diff --git a/docs/_docs/contributing/tools/scalafix.md b/docs/_docs/contributing/tools/scalafix.md deleted file mode 100644 index 30c7050f8b3e..000000000000 --- a/docs/_docs/contributing/tools/scalafix.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: doc-page -title: Working with Scalafix ---- - -First, create a new rule as follows (command from https://scalacenter.github.io/scalafix/docs/developers/setup.html): - -```bash -sbt new scalacenter/scalafix.g8 --repo="Repository Name" -``` - -To run the rule against some codebase: - -```bash -scalafix -r file:scalafix/rules/src/main/scala/fix/YourRule.scala your/code/base/ -``` - -Where `YourRule.scala` is the rule you developed and `your/code/base` is the code base you are running the rule against. diff --git a/docs/_docs/contributing/workflow.md b/docs/_docs/contributing/workflow.md deleted file mode 100644 index 1d11dc61a6bf..000000000000 --- a/docs/_docs/contributing/workflow.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -layout: doc-page -title: Workflow ---- - -Check [Getting Started](getting-started.md) for instructions on how to obtain the source code of dotty. -This document details common workflow patterns when working with Dotty. - -## Compiling files with scalac ## - -As we have seen you can compile a test file either from sbt: - -```bash -$ sbt -> scalac -``` - -or from terminal: - -```bash -$ scalac -``` - -Here are some useful debugging ``: - -* `-Xprint:PHASE1,PHASE2,...` or `-Xprint:all`: prints the `AST` after each - specified phase. Phase names can be found by examining the - `dotty.tools.dotc.transform.*` classes for their `phaseName` field e.g., `-Xprint:erasure`. - You can discover all phases in the `dotty.tools.dotc.Compiler` class -* `-Ylog:PHASE1,PHASE2,...` or `-Ylog:all`: enables `ctx.log("")` logging for - the specified phase. -* `-Ycheck:all` verifies the consistency of `AST` nodes between phases, in - particular checks that types do not change. Some phases currently can't be - `Ycheck`ed, therefore in the tests we run: - `-Ycheck:tailrec,resolveSuper,mixin,restoreScopes,labelDef`. -* the last frontier of debugging (before actual debugging) is the range of logging capabilities that -can be enabled through the `dotty.tools.dotc.config.Printers` object. Change any of the desired printer from `noPrinter` to -`default` and this will give you the full logging capability of the compiler. - -## Inspecting Types with Type Stealer ## - -You can inspect types with the main method `dotty.tools.printTypes` from the sbt shell, -passing at least three arguments: -- The first argument is a string that introduces some -Scala definitions -- The second argument introduces how the the remaining arguments should be interpreted, -comprising of - - `rhs` - the return type of a definition - - `class` - the signature of a class, after its name - - `method` - the signature of a method, after its name - - `type` - the signature of a type, after its name -- The remaining arguments are type signatures, these may reference definitions introduced by the first argument. - -Each type signature is then be printed, displaying their internal structure, alongside their class, using -the same representation that can later be used in pattern matching to decompose the type. - -Here, we inspect a refinement of a class `Box`: -```bash -$ sbt -> scala3-compiler-bootstrapped/Test/runMain dotty.tools.printTypes "class Box { def x: Any }" "rhs" "Box { def x: Int }" -RefinedType(TypeRef(ThisType(TypeRef(NoPrefix, module class )),class Box), x, ExprType(TypeRef(TermRef(ThisType(TypeRef(NoPrefix, module class )), object scala), class Int))) [class dotty.tools.dotc.core.Types$CachedRefinedType] -``` - -You can also pass the empty string as the second -argument, e.g. to inspect a standard library type: -```bash -$ sbt -> scala3-compiler-bootstrapped/Test/runMain dotty.tools.printTypes "" "rhs" "1 *: EmptyTuple" -AppliedType(TypeRef(TermRef(ThisType(TypeRef(NoPrefix, module class )), object scala), class *:), List(ConstantType(Constant(1)), TypeRef(TermRef(ThisType(TypeRef(NoPrefix, module class scala)), object Tuple$package), type EmptyTuple))) -``` - -Here are some other examples you can follow: -- `...printTypes "" class "[T] extends Foo[T] {}"` -- `...printTypes "" method "(x: Int): x.type"` -- `...printTypes "" type "<: Int" "= [T] =>> List[T]"` - -If you want to further inspect the types, and not just print them, the object `dotty.tools.DottyTypeStealer` has a -method `stealType`. It takes the same arguments as `printTypes`, but returns both a `Context` containing the -definitions passed, along with the list of types: -```scala -// compiler/test/dotty/tools/DottyTypeStealer.scala -object DottyTypeStealer extends DottyTest { - - enum Kind: - case `rhs`, `method`, `class`, `type` - ... - - def stealType(kind: Kind, source: String, typeStrings: String*): (Context, List[Type]) = { - ... - } -} -``` -Any test source within `compiler/test` can then call `stealType` for custom purposes. - -## Pretty-printing ## -Many objects in the scalac compiler implement a `Showable` trait (e.g. `Tree`, -`Symbol`, `Type`). These objects may be prettyprinted using the `.show` -method - -## SBT Commands Cheat Sheet ## -The basics of working with Dotty codebase are documented [here](https://dotty.epfl.ch/docs/contributing/getting-started.html) and [here](https://dotty.epfl.ch/docs/contributing/workflow.html). Below is a cheat sheet of some frequently used commands (to be used from SBT console โ€“ `sbt`). - - -| Command | Description | -|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| -| `scala3/scalac` | Run the compiler directly, with any current changes. | -| `scala3/scala` | Run the main method of a given class name. | -| `scalac ../issues/Playground.scala` | Compile the given file โ€“ path relative to the Dotty directory. Output the compiled class files to the Dotty directory itself. | -| `scala Playground` | Run the compiled class `Playground`. Dotty directory is on classpath by default. | -| `repl` | Start REPL | -| `scala3/scalac -print-tasty Foo.tasty` | Print the TASTy of top-level class `Foo` | -| `scala3-bootstrapped/test` | Run all tests for Scala 3. (Slow, recommended for CI only) | -| `scala3-bootstrapped/publishLocal` | Build Scala 3 locally. (Use to debug a specific project) | -| `scalac ../issues/Playground.scala` | Compile the given file โ€“ path relative to the Dotty directory. Output the compiled class files to the Dotty directory itself.| -| `testOnly dotty.tools.dotc.CompilationTests -- *pos` | Run test (method) `pos` from `CompilationTests` suite. | -| `testCompilation sample` | In all test suites, run test files containing the word `sample` in their title. | -| `scala3-compiler/Test/runMain dotty.tools.printTypes`| Print types underlying representation | -| `scaladoc/generateScalaDocumentation` | Build the documentation website (published to https://dotty.epfl.ch) | -| `scaladoc/generateReferenceDocumentation` | Build the reference documentation website (published to https://docs.scala-lang.org/scala3/reference) | - - -## Shell Commands - -| Command | Description | -|--------------------------------------|------------------------------------------------------------------| -| `rm -rv *.tasty *.class out || true` | clean all compiled artifacts, from root dotty directory | - - - - - diff --git a/docs/sidebar.yml b/docs/sidebar.yml index 30ad05d18cf1..941d863a443e 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -166,24 +166,21 @@ subsection: index: contributing/index.md subsection: - page: contributing/getting-started.md - - index: contributing/workflow.md + - page: contributing/setting-up-your-ide.md + - index: contributing/issues/diagnosing-your-issue.md subsection: - page: contributing/issues/reproduce.md - page: contributing/issues/cause.md - page: contributing/issues/areas.md - - page: contributing/issues/debugging.md - - page: contributing/issues/other-debugging.md - - page: contributing/issues/inspection.md - - page: contributing/issues/efficiency.md - - page: contributing/issues/testing.md - - page: contributing/issues/checklist.md - - title: IDEs and Tools - directory: tools - index: contributing/tools/index.md + - index: contributing/debugging/debugging.md subsection: - - page: contributing/tools/ide.md - - page: contributing/tools/mill.md - - page: contributing/tools/scalafix.md + - page: contributing/debugging/ide-debugging.md + - page: contributing/debugging/inspection.md + - page: contributing/debugging/other-debugging.md + - page: contributing/testing.md + - page: contributing/scaladoc.md + - page: contributing/sending-in-a-pr.md + - page: contributing/cheatsheet.md - title: Procedures directory: procedures index: contributing/procedures/index.md diff --git a/scaladoc/README.md b/scaladoc/README.md index 774543996c7a..ee401161b364 100644 --- a/scaladoc/README.md +++ b/scaladoc/README.md @@ -1,151 +1,4 @@ # Scaladoc -Scaladoc is the documentation tool for -[Scala 3](https://github.com/lampepfl/dotty). -It uses the TastyInspector to access definitions, -which is an officially supported way to access Scala 3's perspective of a -codebase. - -We're aiming to support all the features Scaladoc did, plus new and exciting ones such as: - -- Markdown syntax! -- displaying project and API documentation together on one site! -- and more! - -**Yes, this page was generated using scaladoc** - -## Running the project - -Use the following commands to generate documentation for this project and for Dotty, respectively: - -``` -sbt scaladoc/generateSelfDocumentation -sbt scaladoc/generateScalaDocumentation -``` - -To actually view the documentation, the easiest way is to run the following in the project root: - -``` -cd scaladoc/output -python3 -m http.server 8080 -``` - -And afterwards point your browser to or - for this project and for Dotty documentation -respectively. - -It's not strictly necessary to go through an HTTP server, but because of CORS -the documentation won't work completely if you don't. - -## CLI and SBT Documentation - -The preferred way to use scaladoc is calling it from sbt `Compile/doc` task or to use CLI interface provided inside `dotty/bin/scaladoc` bash script. -More information about specific scaladoc flags you can find inside [Usage docs](https://docs.scala-lang.org/scala3/guides/scaladoc/settings.html) - -## Developing - -At least two of our contributors use [Metals](https://scalameta.org/metals/) to -work on the project. - -For every PR named with prefix `scaladoc/`, we build documentation for scaladoc and Dotty. For example, for -PR `scaladoc/update-docs` you can find them at: - -- -- -- - -Note that these correspond to the contents of `output` directory - that's -precisely what they are. - -You can also find the result of building the same sites for latest `master` at: - -- -- -- - -### Testing - -Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation -to signatures found in source files. Such tests are defined using [SignatureTest](test/dotty/tools/scaladoc/signatures/SignatureTest.scala) class -and its subtypes (such as [TranslatableSignaturesTestCases](test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala)) - -WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date. -In case of any discrepancies rely on the source files instead. - -`SignatureTest` requires that you specify the names of the files used to extract signatures, -the names of directories containing corresponding TASTY files -and the kinds of signatures from source files (corresponding to keywords used to declare them like `def`, `class`, `object` etc.) -whose presence in the generated documentation will be checked (other signatures, when missing, will be ignored). -The mentioned source files should be located directly inside [](../scaladoc-testcases/src/tests) directory -but the file names passed as parameters should contain neither this path prefix nor `.scala` suffix. - -By default it's expected that all signatures from the source files will be present in the documentation -but not vice versa (because the documentation can contain also inherited signatures). -To validate that a signature present in the source does not exist in the documentation -(because they should be hidden from users) add `//unexpected` comment after the signature in the same line. -This will cause an error if a signature with the same name appears in the documentation -(even if some elements of the signature are slightly different - to avoid accidentally passing tests). -If the signature in the documentation is expected to slightly differ from how it's defined in the source code -you can add a `//expected: ` comment (also in the same line and followed by a space) followed by the expected signature. -Alternatively you can use `/*<-*/` and `/*->*/` as opening and closing parentheses for parts of a signature present in the source but undesired in the documentation (at least at the current stage of development), e.g. - -``` -def foo/*<-*/()/*->*/: Int -``` - -will make the expected signature be - -``` -def foo: Int -``` - -instead of - -``` -def foo(): Int -``` - -Because of the way how signatures in source are parsed, they're expected to span until the end of a line (including comments except those special ones mentioned above, which change the behaviour of tests) so if a definition contains an implementation, it should be placed in a separate line, e.g. - -``` -def foo: Int - = 1 - -class Bar -{ - //... -} -``` - -Otherwise the implementation would be treated as a part of the signature. - -## Contributing - -We're happy that you'd like to help us! - -We have two issue labels you should take a look at: `good first issue` and -`self-contained`. First is easy pickings: you'll be able to contribute without -needing to dive too deep into the project. Second is reverse: it's an issue -that's you may find interesting, complex and self-contained enough that you can -continue chipping away at it without needing to worry too much about merge -conflicts. - -To contribute to the project with your code, fork this repo and create a pull request from a fresh branch from there. -To keep the history of commits clean, make sure your commits are squashed into one -and all your changes are applied on top of the latest master branch (if not - rebase on it instead of merging it). -Make sure all the tests pass (simply run `sbt test` to verify that). - -## FAQ - - -### Why use TASTy? - -A documentation tool needs to access compiler information about the project - it -needs to list all definitions, resolve them by name, and query their members. -Tasty Reflect is the dedicated way in Scala 3 of accessing this information. - -## Credits - -- [Flatart](https://www.iconfinder.com/Flatart) - Gitter icon - - +You can find the documentation to help better understand and contribute to +scaladoc [here in the contributing guide](https://dotty.epfl.ch/docs/contributing/scaladoc.html).