Fix #2184: Hyper Bootstrap! Integrate the backend as a git submodule

The backend lives in the scalac fork at
https://github.com/lampepfl/scala/tree/sharing-backend. Before this
commit, the scala-compiler built from this fork was a dependency of
Scala just to get this backend. This made it much more cumbersome to
test changes to the backend and also forced us to depend on Scala 2.11.5
since that is the version of scalac that the forked backend is based on.

This commit changes this by adding a git submodule in the
`scala-backend` directory that points to the scalac fork. We do not
compile the whole submodule, instead we add the subset of files we need
to the dotty-compiler project in the sbt build. See backend.md for more
information (online at
http://dotty.epfl.ch/docs/contributing/backend.html) once this commit is
merged.

The most important thing to note is that whenever you clone dotty you
should do `git clone --recursive` to also clone the submodule. If you
already have a cloned dotty you'll need to do:

git submodule update --init

You will need to repeat this command anytime you update dotty and the
backend has been updated, otherwise the content of `scala-backend` will
be stale.

1 files changed, 65 insertions, 0 deletions

diff --git a/docs/docs/contributing/backend.md b/docs/docs/contributing/backend.md
new file mode 100644
index 000000000..e7d98bb7f
--- /dev/null
+++ b/docs/docs/contributing/backend.md
@@ -0,0 +1,65 @@
+---
+layout: doc-page
+title: Working with the backend
+---
+
+The compiler backend is based on a fork of the Scala 2.11 `GenBCode` backend and
+lives at https://github.com/lampepfl/scala/tree/sharing-backend. The dotty
+source tree contains a git submodule in the directory
+[scala-backend](https://github.com/lampepfl/dotty/tree/master/scala-backend)
+that points to this fork. We do not compile every file in this submodule,
+instead we add the subset of files we need to the dotty-compiler project in the
+sbt build.
+
+The most important thing to know when working with git submodules is that
+their content is not automatically updated when you do `git checkout` or `git
+pull`, instead everytime you switch branch, you need to do:
+
+``` shell
+git submodule update --init
+```
+
+## Environment setup
+
+1. Set the following git configuration options to make working with submodules
+easier, see the [Git Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+for more information:
+``` shell
+git config --global diff.submodule log
+git config --global status.submodulesummary 1
+git config --global push.recurseSubmodules check
+```
+
+2. Fork https://github.com/lampepfl/scala (in the following commands,
+   `dotty-staging/scala` is used as a placeholder for your
+   own fork).
+3. ```shell
+   cd scala-backend
+   git remote add scala-staging git@github.com:dotty-staging/scala.git
+   cd ..
+   ```
+
+## Workflow when changing to the backend
+
+```shell
+cd scala-backend
+git checkout -b my-feature-branch
+# Make some changes ...
+
+git push -u scala-backend
+# Open a PR against https://github.com/lampepfl/scala/tree/sharing-backend
+cd ..
+```
+
+Once your PR has been merged into the backend, you'll need to make another PR
+against dotty itself to update the backend, the following commands should be run
+in the root dotty repository, not in the submodule:
+
+``` shell
+# The --remote option will update the submodule to the latest commit in the
+# https://github.com/lampepfl/dotty/tree/master/scala-backend branch
+git submodule update --init --remote
+
+git commit -am "Update backend to include ..."
+# Then push and make a PR against dotty as usual
+```