Information for Akka Developers, #22902

CONTRIBUTING.md

@@ -10,8 +10,6 @@ Depending on which version (or sometimes module) you want to work on, you should
 
 * `master` – active development branch of Akka 2.5.x
 * `release-2.4` – maintenance branch of Akka 2.4.x
-* `release-2.3` – maintenance branch of Akka 2.3.x
-* `artery-dev` – work on the upcoming remoting implementation, codenamed "artery"
 * similarly `release-2.#` branches contain legacy versions of Akka
 
 ## Tags
@@ -88,8 +86,57 @@ The TL;DR; of the above very precise workflow version is:
 6. Keep polishing it until received enough LGTM
 7. Profit!
 
+## sbt
+
+Akka is using the [sbt](https://github.com/sbt/sbt) build system. So the first thing you have to do is to download and install sbt. You can read more about how to do that in the [sbt setup](http://www.scala-sbt.org/0.13/tutorial/index.html) documentation.
+
 Note that the Akka sbt project is large, so `sbt` needs to be run with lots of heap (1-2 GB). This can be specified using a command line argument `sbt -mem 2048` or in the environment variable `SBT_OPTS` but then as a regular JVM memory flag, for example `SBT_OPTS=-Xmx2G`, on some platforms you can also edit the global defaults for sbt in `/usr/local/etc/sbtopts`.
 
+To compile all the Akka core modules use the `compile` command:
+
+```
+sbt compile
+```
+
+You can run all tests with the `test` command:
+
+```
+sbt test
+```
+
+If you want to deploy the artifacts to your local Ivy repository (for example,
+to use from an sbt project) use the `publishLocal` command:
+
+```
+sbt publishLocal
+```
+
+Note that in the examples above we are calling `sbt compile` and `sbt test`
+and so on, but sbt also has an interactive mode. If you just run `sbt` you
+enter the interactive sbt prompt and can enter the commands directly. This saves
+starting up a new JVM instance for each command and can be much faster and more
+convenient.
+
+For example, building Akka as above is more commonly done like this:
+
+```
+% sbt
+[info] Set current project to default (in build file:/.../akka/project/plugins/)
+[info] Set current project to akka (in build file:/.../akka/)
+> compile
+...
+> test
+...
+```
+
+To run a single multi-jvm test:
+
+```
+sbt
+project akka-cluster
+multi-jvm:testOnly akka.cluster.SunnyWeather
+```
+
 ## The `validatePullRequest` task
 
 The Akka build includes a special task called `validatePullRequest` which investigates the changes made as well as dirty
@@ -169,20 +216,20 @@ Whether or not a pull request (or parts of it) shall be back- or forward-ported
 
 ## Documentation
 
-All documentation must abide by the following maxims:
+All documentation is preferred to be in Lightbend's standard documentation format [Paradox](https://github.com/lightbend/paradox), which among other things allows all code in the documentation to be externalized into compiled files and imported into the documentation.
 
-- Example code should be run as part of an automated test suite.
-- Version should be **programmatically** specifiable to the build.
-- Generation should be **completely automated** and available for scripting.
-- Artifacts that must be included in the Lightbend stack should be published to a maven “documentation” repository as documentation artifacts.
+To build the documentation locally:
 
-All documentation is preferred to be in Lightbend's standard documentation format [reStructuredText](http://doc.akka.io/docs/akka/snapshot/dev/documentation.html) compiled using Lightbend's customized [Sphinx](http://sphinx.pocoo.org/) based documentation generation system, which among other things allows all code in the documentation to be externalized into compiled files and imported into the documentation.
+```
+sbt
+akka-docs/paradox
+```
 
-To learn about how to build the documentation locally see the Reference Docs section about this topic: [Build the documentation]( http://doc.akka.io/docs/akka/2.4/dev/documentation.html#Build_the_documentation).
+The generated html documentation is in `akka-docs/target/paradox/site/main/index.html`.
 
-For more info, or for a starting point for new projects, look at the [Lightbend Documentation Template project](https://github.com/typesafehub/doc-template).
+### Scaladoc
 
-For larger projects that have invested a lot of time and resources into their current documentation and samples scheme (like for example Play), it is understandable that it will take some time to migrate to this new model. In these cases someone from the project needs to take the responsibility of manual QA and verifier for the documentation and samples.
+Akka generates class diagrams for the API documentation using ScalaDoc. This needs the `dot` command from the Graphviz software package to be installed to avoid errors. You can disable the diagram generation by adding the flag `-Dakka.scaladoc.diagrams=false`. After installing Graphviz, make sure you add the toolset to the PATH (definitely on Windows).
 
 ### JavaDoc