improve README (#5163)

3 files changed, 287 insertions, 185 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 617734210f..47d2788623 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,7 +8,7 @@ In 2014, you -- the Scala community -- matched the core team at EPFL in number o
 
 We are super happy about this, and are eager to make your experience contributing to Scala productive and satisfying, so that we can keep up this growth. We can't do this alone (nor do we want to)!
 
-This is why we're collecting these notes on how to contribute, and we hope you'll share your experience to improve the process for the next contributor! (Feel free to send a PR for this note, send your thoughts to scala-internals, or tweet about it to @adriaanm.)
+This is why we're collecting these notes on how to contribute, and we hope you'll share your experience to improve the process for the next contributor! (Feel free to send a PR for this note, send your thoughts to gitter, scala-internals, or tweet about it to @adriaanm.)
 
 By the way, the team at Lightbend is: @adriaanm, @lrytz, @retronym, @SethTisue, and @szeiger.
 
@@ -117,14 +117,32 @@ See the [scala-jenkins-infra repo](https://github.com/scala/scala-jenkins-infra)
 
 ### Pass code review
 
-Your PR will need to be assigned to one or more reviewers.  You can suggest reviewers yourself; if you're not sure, see the list in [README.md](README.md) or ask on scala-internals.
+Your PR will need to be assigned to one or more reviewers. You can suggest reviewers
+yourself; if you're not sure, see the list in [README.md](README.md) or ask on gitter
+or scala-internals.
 
-To assign a reviewer, add a "review by @reviewer" to your PR description.
+To assign a reviewer, add a "review by @reviewer" to the PR description or in a
+comment on your PR.
 
 NOTE: it's best not to @mention in commit messages, as github pings you every time a commit with your @name on it shuffles through the system (even in other repos, on merges,...).
 
 A reviewer gives the green light by commenting "LGTM" (looks good to me).
 
-A review feedback may be addressed by pushing new commits to the request, if these commits stand on their own.
+When including review feedback, we typically amend the changes into the existing commit(s)
+and `push -f` to the branch. This is to keep the git history clean. Additional commits
+are OK if they stand on their own.
 
-Once all these conditions are met, and we agree with the change (we are available on scala-internals to discuss this beforehand, before you put in the coding work!), we will merge your changes.
+Once all these conditions are met, and we agree with the change (we are available on
+gitter or scala-internals to discuss this beforehand, before you put in the coding work!),
+we will merge your changes.
+
+We use the following labels:
+
+Label                    | Description
+-------------------------|:-----------
+`reviewed`               | automatically added by scabot when a comment prefixed with LGTM is posted
+`welcome`                | added by reviewer / queue curator to welcome someone's first PR (for highlighting in the release notes)
+`release-notes`          | added by reviewer / queue curator to make sure this PR is highlighted in the release notes
+`on-hold`                | added when this PR should not yet be merged, even though CI is green
+`WIP`                    | added by the author if a PR is submitted for CI testing, needs more work to be complete
+`assistance-appreciated` | added by the author if help by the community is appreciated to move a change forward
diff --git a/README.md b/README.md
index dc869da0da..6ebb453176 100644
--- a/README.md
+++ b/README.md
@@ -5,12 +5,12 @@ This is the official repository for the [Scala Programming Language](http://www.
 
 To contribute to the Scala Standard Library, Scala Compiler and Scala Language Specification, please send us a [pull request](https://help.github.com/articles/using-pull-requests/#fork--pull) from your fork of this repository! We do have to ask you to sign the [Scala CLA](http://www.lightbend.com/contribute/cla/scala) before we can merge any of your work into our code base, to protect its open source nature.
 
-For more information on building and developing the core of Scala, read on!
+For more information on building and developing the core of Scala, make sure to read
+the rest of this README!
 
-Please also check out:
-
-* our [guidelines for contributing](CONTRIBUTING.md).
-* the ["Scala Hacker Guide"](http://scala-lang.org/contribute/hacker-guide.html) covers some of the same ground as this README, but in greater detail and in a more tutorial style, using a running example.
+In order to get in touch with Scala contributors, join the
+[scala/contributors](https://gitter.im/scala/contributors) gitter channel or post on the
+[scala-internals mailing list](http://www.scala-lang.org/community/).
 
 # Reporting issues
 
@@ -18,195 +18,247 @@ We're still using Jira for issue reporting, so please [report any issues](https:
 (We would love to start using GitHub Issues, but we're too resource-constrained to take on this migration right now.)
 
 # Get in touch!
-If you need some help with your PR at any time, please feel free to @-mention anyone from the list below (or simply `@scala/team-core-scala`), and we will do our best to help you out:
+If you need some help with your PR at any time, please feel free to @-mention anyone from the list below, and we will do our best to help you out:
 
                                                                                                   | username                                                       | talk to me about...                               |
 --------------------------------------------------------------------------------------------------|----------------------------------------------------------------|---------------------------------------------------|
- <img src="https://avatars.githubusercontent.com/adriaanm"     height="50px" title="Adriaan Moors"/>        | [`@adriaanm`](https://github.com/adriaanm)           | type checker, pattern matcher, infrastructure, language spec |
- <img src="https://avatars.githubusercontent.com/SethTisue"    height="50px" title="Seth Tisue"/>           | [`@SethTisue`](https://github.com/SethTisue)         | build, developer docs, community build, Jenkins, library, the welcome-to-Scala experience |
- <img src="https://avatars.githubusercontent.com/retronym"     height="50px" title="Jason Zaugg"/>          | [`@retronym`](https://github.com/retronym)           | compiler performance, weird compiler bugs, Java 8 lambdas, REPL |
- <img src="https://avatars.githubusercontent.com/Ichoran"      height="50px" title="Rex Kerr"/>             | [`@Ichoran`](https://github.com/Ichoran)             | collections library, performance              |
- <img src="https://avatars.githubusercontent.com/lrytz"        height="50px" title="Lukas Rytz"/>           | [`@lrytz`](https://github.com/lrytz)                 | optimizer, named & default arguments              |
- <img src="https://avatars.githubusercontent.com/VladUreche"   height="50px" title="Vlad Ureche"/>          | [`@VladUreche`](https://github.com/VladUreche)       | specialization, Scaladoc tool |
- <img src="https://avatars.githubusercontent.com/densh"        height="50px" title="Denys Shabalin"/>       | [`@densh`](https://github.com/densh)                 | quasiquotes, parser, string interpolators, macros in standard library |
- <img src="https://avatars.githubusercontent.com/xeno-by"      height="50px" title="Eugene Burmako"/>       | [`@xeno-by`](https://github.com/xeno-by)             | macros and reflection |
- <img src="https://avatars.githubusercontent.com/heathermiller" height="50px" title="Heather Miller"/>      | [`@heathermiller`](https://github.com/heathermiller) | documentation |
- <img src="https://avatars.githubusercontent.com/dickwall"     height="50px" title="Dick Wall"/>            | [`@dickwall`](https://github.com/dickwall)           | process & community, documentation |
- <img src="https://avatars.githubusercontent.com/dragos"       height="50px" title="Iulian Dragos"/>        | [`@dragos`](https://github.com/dragos)               | specialization, back end |
- <img src="https://avatars.githubusercontent.com/axel22"       height="50px" title="Aleksandr Prokopec"/>   | [`@axel22`](https://github.com/axel22)               | collections, concurrency, specialization |
- <img src="https://avatars.githubusercontent.com/janekdb"      height="50px" title="Janek Bogucki"/>        | [`@janekdb`](https://github.com/janekdb)             | documentation |
+ <img src="https://avatars.githubusercontent.com/adriaanm"      height="50px" title="Adriaan Moors"/>        | [`@adriaanm`](https://github.com/adriaanm)           | type checker, pattern matcher, infrastructure, language spec |
+ <img src="https://avatars.githubusercontent.com/SethTisue"     height="50px" title="Seth Tisue"/>           | [`@SethTisue`](https://github.com/SethTisue)         | build, developer docs, community build, Jenkins, library, the welcome-to-Scala experience |
+ <img src="https://avatars.githubusercontent.com/retronym"      height="50px" title="Jason Zaugg"/>          | [`@retronym`](https://github.com/retronym)           | compiler performance, weird compiler bugs, Java 8 lambdas, REPL |
+ <img src="https://avatars.githubusercontent.com/Ichoran"       height="50px" title="Rex Kerr"/>             | [`@Ichoran`](https://github.com/Ichoran)             | collections library, performance              |
+ <img src="https://avatars.githubusercontent.com/lrytz"         height="50px" title="Lukas Rytz"/>           | [`@lrytz`](https://github.com/lrytz)                 | optimizer, named & default arguments              |
+ <img src="https://avatars.githubusercontent.com/VladUreche"    height="50px" title="Vlad Ureche"/>          | [`@VladUreche`](https://github.com/VladUreche)       | specialization, Scaladoc tool |
+ <img src="https://avatars.githubusercontent.com/densh"         height="50px" title="Denys Shabalin"/>       | [`@densh`](https://github.com/densh)                 | quasiquotes, parser, string interpolators, macros in standard library |
+ <img src="https://avatars.githubusercontent.com/xeno-by"       height="50px" title="Eugene Burmako"/>       | [`@xeno-by`](https://github.com/xeno-by)             | macros and reflection |
+ <img src="https://avatars.githubusercontent.com/heathermiller" height="50px" title="Heather Miller"/>      | [`@heathermiller`](https://github.com/heathermiller)  | documentation |
+ <img src="https://avatars.githubusercontent.com/dickwall"      height="50px" title="Dick Wall"/>            | [`@dickwall`](https://github.com/dickwall)           | process & community, documentation |
+ <img src="https://avatars.githubusercontent.com/dragos"        height="50px" title="Iulian Dragos"/>        | [`@dragos`](https://github.com/dragos)               | specialization, back end |
+ <img src="https://avatars.githubusercontent.com/axel22"        height="50px" title="Aleksandr Prokopec"/>   | [`@axel22`](https://github.com/axel22)               | collections, concurrency, specialization |
+ <img src="https://avatars.githubusercontent.com/janekdb"       height="50px" title="Janek Bogucki"/>        | [`@janekdb`](https://github.com/janekdb)             | documentation |
 
 P.S.: If you have some spare time to help out around here, we would be delighted to add your name to this list!
 
-# Handy Links
-  - [A wealth of documentation](http://docs.scala-lang.org)
-  - [mailing lists](http://www.scala-lang.org/community/)
-  - [Gitter room for Scala contributors](https://gitter.im/scala/contributors)
-  - [Scala CI](https://scala-ci.typesafe.com/)
-  - download the latest nightlies:
-      - [2.11.x](http://www.scala-lang.org/files/archive/nightly/2.11.x/)
-      - [2.12.x](http://www.scala-lang.org/files/archive/nightly/2.12.x/)
-
 # Repository structure
 
 ```
 scala/
-+--build.xml                 The main Ant build script, see also under src/build.
-+--pull-binary-libs.sh       Pulls binary artifacts from remote repository.
-+--lib/                      Pre-compiled libraries for the build.
-+--src/                      All sources.
-   +---/library              Scala Standard Library.
-   +---/reflect              Scala Reflection.
-   +---/compiler             Scala Compiler.
-   +---/eclipse              Eclipse project files.
-   +---/intellij             IntelliJ project templates.
++--build.sbt                 The main sbt build script
++--build.xml                 The deprecated Ant build script
++--pull-binary-libs.sh       Pulls binary artifacts from remote repository, used by build scripts
++--lib/                      Pre-compiled libraries for the build
++--src/                      All sources
+   +---/library              Scala Standard Library
+   +---/reflect              Scala Reflection
+   +---/compiler             Scala Compiler
+   +---/eclipse              Eclipse project files
+   +---/intellij             IntelliJ project templates
++--spec/                     The Scala language specification
 +--scripts/                  Scripts for the CI jobs (including building releases)
-+--test/                     The Scala test suite.
-+--build/                    [Generated] Build products output directory for ant.
-+--dist/                     [Generated] The destination folder for Scala distributions.
++--test/                     The Scala test suite
+   +---/files                Partest tests
+   +---/junit                JUnit tests
++--build/                    [Generated] Build output directory
 ```
 
-# How we roll
+# Get Ready to Contribute
 
 ## Requirements
 
-You'll need a Java SDK.  The baseline version is 6 for 2.11.x, 8 for
-2.12.x. (It's also possible to use a later SDK for local development,
-but the CI will verify against the baseline version.)
-
-You'll also need Apache Ant (version 1.9.3 or above) and curl (for `./pull-binary-libs.sh`).
-
-Mac OS X and Linux work. Windows may work if you use Cygwin. (Community help with keeping the build working on Windows is appreciated.)
-
-## Git Hygiene
-
-As git history is forever, we take great pride in the quality of the commits we merge into the repository. The title of your commit will be read hundreds (of thousands? :-)) of times, so it pays off to spend just a little bit more time to polish it, making it descriptive and concise. Please take a minute to read the advice [most projects agree on](https://github.com/erlang/otp/wiki/Writing-good-commit-messages), and stick to 72 or fewer characters for the first line, wrapping subsequent ones at 80 (at most).
-
-When not sure how to formulate your commit message, imagine you're writing a bullet item for the next release notes, or describing what the commit does to the code base (use active verbs in the present tense). When your commit title is featured in the next release notes, it will be read by a lot of curious Scala users, looking for the latest improvements. Satisfy their thirst for information with as few words as possible! Also, a commit should convey clearly to your (future) fellow contributors what it does to the code base.
-
-Writing the commit message is a great sanity check that the commit is of the right size. If it does too many things, the description will be unwieldy and tedious to write. Chop it up (`git add -u --patch` and `git rebase` are your friends) and simplify!
-
-To pinpoint bugs, we often use git bisect, which is only effective when we can count on each commit building (and passing the test suite). Thus, the CI bot enforces this. Please rebase your development history into a sensible list of self-contained commits that tell the story of your bug fix or improvement. Carve them up so that the riskier bits can be reverted independently. Keep changes focussed by splitting out cleanups from refactorings from actual changes to the logic.
-
-This facilitates reviewing: a commit that reformats code can be judged quickly not to affect anything, so we can focus on the meat of the PR. It also helps when merging between long-running branches, reducing conflicts (or providing at least a limited scope for each one).
-
-Please do not @-mention anyone in the commit message -- that's what the PR description and comments are for. Every time a commit is shuffled through github (in a merge in some fork, say), every @-mention results in an email to that person (the core team treats them as personal email, straight to their inbox, so please don't flood us :-)).
-
-
-## Reviews
-
-Please consider nominating a reviewer for your PR in the PR's description or a comment. If unsure, not to worry -- the core team will assign one for you.
-
-Your reviewer is also your mentor, who will help you rework your PR so that it meets our requirements. We strive to give timely feedback, and apologize for those times when we are overwhelmed by the volume of contributions. Please feel free to ping us. You are entitled to regular progress updates and at least a quick assessment of feasibility of a bigger PR.
-
-To help you plan your contributions, we communicate our plans on a regular basis on scala-internals, and deadlines are tracked as due dates for [GitHub milestones](https://github.com/scala/scala/milestones).
-
-## Reviewing
-
-Once you've gained some experience with the code base and the process, the next step is to review the contributions of others.
-
-The main goal of this whole process is to ensure the health of the Scala project by improving the quality of the code base, the documentation, as well as this process itself. Thank you for doing your part!
-
-## [Labels](https://github.com/scala/scala/labels)
-
-Label           | Description
---------------- | -----------
-`reviewed`      | automatically added by scabot when a comment prefixed with LGTM is posted
-`welcome`       | reviewer / queue curator adds to welcome someone's first PR (for highlighting in the release notes)
-`release-notes` | reviewer / queue curator adds to make sure this PR is highlighted in the release notes
-`on-hold`       | added when this PR should not yet be merged, even though CI is green
-
-### Tips & Tricks
-Once the `publish-core` task has completed on a commit, you can try it out in sbt as follows:
+You need the following tools:
+  - A Java SDK. The baseline version is 6 for 2.11.x, 8 for 2.12.x. It's possible
+  to use a later SDK for local development, but the CI will verify against the baseline
+  version.
+  - sbt, we recommend the [sbt-extras](https://github.com/paulp/sbt-extras) runner
+  script. It provides sensible default jvm options (stack and heap size).
+  - curl (for `./pull-binary-libs.sh`, used by the sbt / ant build).
+  - Apache Ant (version 1.9.3 or above) if you need to use the (deprecated) ant build.
+
+Mac OS X and Linux work. Windows may work if you use Cygwin. Community help with keeping
+the build working on Windows is appreciated.
+
+## Build Setup
+
+### Basics
+
+Scala is built in layers, where each layer is a complete Scala compiler and library.
+Here is a short description of the layers, from bottom to top:
+
+  - `starr`: the stable reference Scala release. We use an official release of
+    Scala (specified by `starr.version` in [versions.properties](versions.properties)),
+    downloaded from the Central Repository.
+  - `locker` (deprecated, only in ant): an intermediate layer that existed in the
+    ant build to perform a bootstrap.
+  - `quick`: the development layer which is incrementally built when working on
+    changes in the compiler or library.
+  - `strap` (deprecated, only in ant) : a test layer used to check stability of
+    the build.
+
+The sbt build uses `starr` to build `quick`. This is sufficient for most development
+scenarios: changes to the library or the compiler can be tested by running the `quick`
+Scala (see below for how to do that).
+
+However, a full build of Scala (a *bootstrap*, as performed by our CI) requires two
+layers. This guarantees that every Scala version can build itself. If you change the
+code generation part of the Scala compiler, your changes will only reflect in the
+bytecode of the library and compiler after a bootstrap. See below for how to create
+a bootstrap build locally.
+
+### Using the Sbt Build
+
+Core commands:
+  - `compile` compiles all sub-projects (library, reflect, compiler, scaladoc, etc)
+  - `scala` / `scalac` run the REPL / compiler directly from sbt (accept options /
+    arguments)
+  - `dist/mkBin` generates runner scripts (`scala`, `scalac`, etc) in `build/quick/bin`
+  - `dist/mkPack` creates a build in the Scala distribution format in `build/pack`
+  - `test` runs the JUnit test, `testOnly *immutable.ListTest` runs a subset
+  - `partest` runs partest tests (accepts options, try `partest --help`)
+  - `publishLocal` publishes a distribution locally (can be used as `scalaVersion` in
+    other sbt projects)
+    - Optionally `set VersionUtil.baseVersionSuffix in Global := "abcd123-SNAPSHOT"`
+      where `abcd123` is the git hash of the revision being published. You can also
+      use something custom like `"mypatch"`. This changes the version number from
+      `2.12.0-SNAPSHOT` to something more stable (`2.12.0-abcd123-SNAPSHOT`).
+    - Optionally `set publishArtifact in (Compile, packageDoc) in ThisBuild := false`
+      to skip generating / publishing API docs (speeds up the process).
+
+#### Sandbox
+
+We recommend to keep local test files in the `sandbox` directory which is listed in
+the `.gitignore` of the Scala repo.
+
+#### Incremental Compilation
+
+Note that sbt's incremental compilation is often too coarse for the Scala compiler
+codebase and re-compiles too many files, resulting in long build times (check
+[sbt#1104](https://github.com/sbt/sbt/issues/1104) for progress on that front). In the
+meantime you can:
+  - Enable "ant mode" in which sbt only re-compiles source files that were modified.
+    Create a file `local.sbt` containing the line `(incOptions in ThisBuild) := (incOptions in ThisBuild).value.withNameHashing(false).withAntStyle(true)`.
+    Add an entry `local.sbt` to your `~/.gitignore`.
+  - Use IntelliJ IDEA for incremental compiles (see [IDE Setup](#ide-setup) below) - its
+    incremental compiler is a bit less conservative, but usually correct.
+
+#### Local Bootstrap Build
+
+To perform a bootstrap using sbt
+  - first a build is published either locally or on a temporary repository,
+  - then a separate invocation of sbt (using the previously built version as `starr`)
+    is used to build / publish the actual build.
+
+Assume the current `starr` version is `2.12.0-M4` (defined in
+[versions.properties](versions.properties)) and the current version is `2.12.0-SNAPSHOT`
+(defined in [build.sbt](build.sbt)). To perform a local bootstrap:
+  - Run `publishLocal` (you may want to specify a custom version suffix and skip
+    generating API docs, see above).
+  - Quit sbt and start a new sbt instance using `sbt -Dstarr.version=<version>` where
+    `<version>` is the version number you published locally.
+  - If the version number you published is not binary compatible with the current
+    `starr`, `set every scalaBinaryVersion := "2.12.0-M4"`. This is not required if
+    the version you published locally is binary compatible, i.e., if the current
+    `starr` is a 2.12.x release and not a milestone / RC.
+
+The last step is required to resolve modules (scala-xml, scala-partest, etc). It
+assumes that the module releases for the current `starr` work (in terms of binary
+compatibility) with the local starr that you published locally. A full bootstrap
+requires re-building the all the modules. On our CI this is handled by the
+[bootstrap](scripts/jobs/integrate/bootstrap) script, but it (currently) cannot
+be easily executed locally.
+
+### IDE Setup
+
+You may use IntelliJ IDEA ([src/intellij/README.md](src/intellij/README.md)) or the
+Scala IDE for Eclipse (see [src/eclipse/README.md](src/eclipse/README.md)).
+
+In order to use IntelliJ's incremental compiler:
+  - run `dist/mkBin` in sbt to get a build and the runner scripts in `build/quick/bin`
+  - run "Build" - "Make Project" in IntelliJ
+
+Now you can edit and build in IntelliJ and use the scripts (compiler, REPL) to
+directly test your changes. You can also run the `scala`, `scalac` and `partest`
+commands in sbt. Enable "ant mode" (explained above) to prevent sbt's incremental
+compiler from re-compiling (too many) files before each `partest` invocation.
+
+# Coding Guidelines
+
+Our guidelines for contributing are explained in [CONTRIBUTING.md](CONTRIBUTING.md).
+It contains useful information on our coding standards, testing, documentation, how
+we use git and GitHub and how to get your code reviewed.
+
+You may also want to check out the following resources:
+  - The ["Scala Hacker Guide"](http://scala-lang.org/contribute/hacker-guide.html)
+    covers some of the same ground as this README, but in greater detail and in a more
+    tutorial style, using a running example.
+  - [Scala documentation site](http://docs.scala-lang.org)
+
+# Scala CI
+
+Once you submit a PR your commits will are automatically tested by the Scala CI.
+
+If you see a spurious build failure, you can post `/rebuild` as a PR comment.
+The [scabot README](https://github.com/scala/scabot) lists all available commands.
+
+If you'd like to test your patch before having everything polished for review,
+feel free to submit a PR and add the `WIP` label. In case your WIP branch contains
+a large number of commits (that you didn't clean up / squash yet for review),
+consider adding `[ci: last-only]` to the PR title. That way only the last commit
+will be tested, saving some energy and CI-resources. Note that inactive WIP PRs
+will be closed eventually, which does not mean the change is being rejected.
+
+CI performs a full bootstrap. The first task, `validate-publish-core`, publishes
+a build of your commit to the temporary repository
+https://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots.
+Note that this build is not yet bootstrapped, its bytecode is built using the
+current `starr`. The version number is `2.12.0-abcd123-SNAPSHOT` where `abcd123`
+is the commit hash.
+
+You can use Scala builds in the validation repository locally by adding a resolver
+and specifying the corresponding `scalaVersion`:
 
 ```
 $ sbt
-
 > set resolvers += "pr" at "https://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots/"
-> set scalaVersion := "<milestone>-<sha7>-SNAPSHOT"
+> set scalaVersion := "2.12.0-abcd123-SNAPSHOT"
 > console
 ```
 
-Here, `<milestone>` is the milestone targeted by the PR (e.g., 2.11.6), and `<sha7>` is the 7-character sha (the format used by GitHub on the web).
-
-## IDE Setup
-### Eclipse
-See [src/eclipse/README.md](src/eclipse/README.md).
-
-### IntelliJ 15
-See [src/intellij/README.md](src/intellij/README.md).
-
-## Building with sbt (EXPERIMENTAL)
-
-The experimental sbt-based build definition has arrived! Run `sbt package`
-to build the compiler. You can run `sbt test` to run unit (JUnit) tests.
-Use `sbt test/it:test` to run integration (partest) tests.
-
-We would like to migrate to sbt build as quickly as possible. If you would
-like to help please use the scala-internals mailing list to discuss your
-ideas and coordinate your effort with others.
-
-## Building with Ant
+Note that the scala modules are currently not built / published against the
+tested version during CI validation.
 
-NOTE: we are working on migrating the build to sbt.
+## Nightly Builds
 
-If you are behind a HTTP proxy, include
-[`ANT_ARGS=-autoproxy`](https://ant.apache.org/manual/proxy.html) in
-your environment.
+The Scala CI builds nightly download releases (including all modules) and publishes
+them to the following locations:
+  - [2.12.x](http://www.scala-lang.org/files/archive/nightly/2.12.x/?C=M;O=D)
+  - [2.11.x](http://www.scala-lang.org/files/archive/nightly/2.11.x/?C=M;O=A)
 
-Run `ant build-opt` to build an optimized version of the compiler.
-Verify your build using `ant test-opt`.
+The CI also publishes nightly API docs:
+  - [2.12.x](http://www.scala-lang.org/files/archive/nightly/2.12.x/api/?C=M;O=D)
+    - [symlink to the latest](http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/)
+  - [2.11.x](http://www.scala-lang.org/files/archive/nightly/2.11.x/api/?C=M;O=D)
+    - [symlink to the latest](http://www.scala-lang.org/files/archive/nightly/2.11.x/api/2.11.x/)
 
-The Scala build system is based on Apache Ant. Most required pre-compiled
-libraries are part of the repository (in 'lib/'). The following however is
-assumed to be installed on the build machine: TODO
+Note that we currently don't publish nightly (or SNAPSHOT) builds in maven or ivy
+format to any repository. You can track progress on this front at
+[scala-jenkins-infra#133](https://github.com/scala/scala-jenkins-infra/issues/133)
+and [scala-dev#68](https://github.com/scala/scala-dev/issues/68).
 
-### Ant Tips and tricks
+## Scala CI Internals
 
-Here are some common commands. Most ant targets offer a `-opt` variant that runs under `-optimise` (CI runs the -optimize variant).
-
-Command                 | Description
------------------------ | -----------
-`./pull-binary-libs.sh` | downloads all binary artifacts associated with this commit.
-`ant -p`                | prints out information about the commonly used ant targets.
-`ant` or `ant build`    | A quick compilation (to `build/quick`) of your changes using the locker compiler.
-`ant dist`              | builds a distribution in 'dists/latest'.
-`ant all.clean`         | removes all build files and all distributions.
-
-A typical debug cycle incrementally builds quick, then uses it to compile and run the file
-`sandbox/test.scala` as follows:
-
-  - `ant && build/quick/bin/scalac -d sandbox sandbox/test.scala && build/quick/bin/scala -cp sandbox Test`
-
-We typically alias `build/quick/bin/scalac -d sandbox` to `qsc` and `build/quick/bin/scala -cp sandbox` to `qs` in our shell.
-
-`ant test-opt` tests that your code is working and fit to be committed:
-
-  - Runs the test suite and bootstrapping test on quick.
-  - You can run the suite only (skipping strap) with `ant test.suite`.
-
-`ant docs` generates the HTML documentation for the library from the sources using the scaladoc tool in quick.
-Note: on most machines this requires more heap than is allocated by default.  You can adjust the parameters with `ANT_OPTS`. Example command line:
-
-```sh
-ANT_OPTS="-Xms512M -Xmx2048M -Xss1M" ant docs
-```
+The Scala CI runs as a Jenkins instance on [scala-ci.typesafe.com](https://scala-ci.typesafe.com/),
+configured by a chef cookbook at [scala/scala-jenkins-infra](https://github.com/scala/scala-jenkins-infra).
 
-### Bootstrapping concepts
-NOTE: This is somewhat outdated, but the ideas still hold.
+The build bot that watches PRs, triggers testing builds and applies the "reviewed" label
+after an LGTM comment is in the [scala/scabot](https://github.com/scala/scabot) repo.
 
-In order to guarantee the bootstrapping of the Scala compiler, the ant build
-compiles Scala in layers. Each layer is a complete compiled Scala compiler and library.
-A superior layer is always compiled by the layer just below it. Here is a short
-description of the four layers that the build uses, from bottom to top:
+## Community Build
 
-  - `starr`: the stable reference Scala release. We use an official version of Scala (specified by `starr.version` in `versions.properties`), downloaded from the Central Repository.
-  - `locker`: the local reference which is compiled by starr and is the work compiler in a typical development cycle. Add `locker.skip=true` to `build.properties` to skip this step and speed up development when you're not changing code generation. In any case, after it has been built once, it is “frozen” in this state. Updating it to fit the current source code must be explicitly requested (`ant locker.unlock`).
-  - `quick`: the layer which is incrementally built when testing changes in the compiler or library. This is considered an actual new version when locker is up-to-date in relation to the source code.
-  - `strap`: a test layer used to check stability of the build.
+The community build is a central element for testing Scala releases. A community
+build can be launched for any Scala revision / commit. It first builds the Scala
+library and compiler and then uses that Scala version to build a large number of
+open-source projects from source.
 
-For each layer, the Scala library is compiled first and the compiler next.
-That means that any changes in the library can immediately be used in the
-compiler without an intermediate build. On the other hand, if building the
-library requires changes in the compiler, a new locker must be built if
-bootstrapping is still possible, or a new starr if it is not.
+Community builds run on the Scala Jenkins instance, the jobs are named
+`..-integrate-community-build`. The community build definitions specifying which
+projects are built are in the
+[scala/community-builds](https://github.com/scala/community-builds) repo.
diff --git a/src/intellij/README.md b/src/intellij/README.md
index dcad699d43..41fef04183 100644
--- a/src/intellij/README.md
+++ b/src/intellij/README.md
@@ -1,25 +1,25 @@
-# Building Scala in IntelliJ IDEA
-
-## Requirements
+# Developing Scala in IntelliJ IDEA
 
 Use the latest IntelliJ release and install the Scala plugin from within the IDE.
 
-## Initial setup
+## Initial Setup
 
 To create the IntelliJ project files:
 
   - Run `sbt intellij`
   - Open `src/intellij/scala.ipr` in IntelliJ
-  - In `File` → `Project Structure` → `Project` → `Project SDK`, create an SDK entry named "1.8" containing the Java 1.8 SDK
+  - In `File` → `Project Structure` → `Project` → `Project SDK`, create an SDK entry
+    named "1.8" containing the Java 1.8 SDK (1.6 if you're on the Scala the 2.11.x branch)
 
-The project files are created by as copies of the `.SAMPLE` files, which are under version control.
-The actual IntelliJ project files are in `.gitignore` so that local changes are ignored.
+The project files are created as copies of the `.SAMPLE` files, which are under version
+control. The actual IntelliJ project files are in `.gitignore` so that local changes
+are ignored.
 
 ## Dependencies
 
 For every module in the IntelliJ project there is a corresponding `-deps` library, for exmaple `compiler-deps` provides `ant.jar` for the compiler codebase.
 The `.jar` files in these `-deps` libraries can be easily kept up-to-date by running `sbt intellij` again.
-This is necessary whenever the dependencies in the sbt build change, for example when the STARR version is updated.
+This is necessary whenever the dependencies in the sbt build change, for example when the `starr` version is updated.
 
 Note that this command only patches the dependency lists, all other settings in the IntelliJ project definition are unchanged.
 To overwrite the project definition files by copying the `.SAMPLE` files again run `sbt intellijFromSample`.
@@ -33,17 +33,49 @@ When switching between 2.11.x and 2.12.x, make sure to run `sbt intellij`.
 Note that the `Project SDK` is not updated in this process.
 If you want to use the Java 1.6 SDK while working on 2.11.x you need to change it manually (`File` → `Project Structure` → `Project` → `Project SDK`).
 
-## Usage
+If you switch between 2.11.x and 2.12.x often, it makes sense to have a separate clone
+of the repository for each branch.
+
+## Incremental Compilation
+
+Run `Build` → `Make Project` to build all modules of the Scala repository (library,
+compiler, etc). Note that compilation IntelliJ is performed in a single pass (no
+bootstrap), like the sbt build.
+
+Note that the output directory when compiling in IntelliJ is the same as for the
+sbt and (deprecated) ant builds. This allows building incrementally in IntelliJ
+and directly use the changes using the command-line scripts in `build/quick/bin/`.
+
+## Running JUnit Tests
+
+JUnit tests can be executed by right-clicking on a test class or test method and
+selecting "Run" or "Debug". The debugger will allow you to stop at breakpoints
+within the Scala library.
+
+It is possible to invoke the Scala compiler from a JUnit test (passing the source
+code as a string) and inspect the generated bytecode, see for example
+`scala.issues.BytecodeTest`. Debugging such a test is an easy way to stop at
+breakpoints within the Scala compiler.
+
+## Running the Compiler and REPL
+
+You can create run/debug configurations to run the compiler and REPL directly within
+IntelliJ, which might accelerate development and debugging of the the compiler.
 
-Compiling, running, JUnit tests and debugging should all work.
-You can work on the compiler, the standard library, and other components as well.
+To debug the Scala codebase you can also use "Remote" debug configuration and pass
+the corresponding arguments to the jvm running the compiler / program.
 
-Note that compilation within IntelliJ is performed in a single pass.
-The code is compiled using the "STARR" (stable reference) compiler, as specified by `starr.version` in `versions.properties`.
-This is consistent with the sbt build.
+To run the compiler create an "Application" configuration with
+  - Main class: `scala.tools.nsc.Main`
+  - Program arguments: `-usejavacp -cp sandbox -d sandbox sandbox/Test.scala`
+  - Working directory: the path of your checkout
+  - Use classpath of module: `compiler`
 
-Note that the output directory when compiling in IntelliJ is the same as for the sbt build.
-This allows building incrementally in IntelliJ and directly use the changes using the command-line scripts in `build/quick/bin/`.
+To run the REPL create an "Application" configuration with
+  - Main class: `scala.tools.nsc.MainGenericRunner`
+  - Program arguments: `-usejavacp`
+  - Working directory: the path of your checkout
+  - Use classpath of module: `repl`
 
 ## Updating the `.SAMPLE` files