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.
+To build the documentation locally:
-- 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.
 
-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
 

akka-docs/src/main/paradox/java.md

@@ -15,7 +15,6 @@
 * [common/other-modules](java/common/other-modules.md)
 * [java/howto](java/howto.md)
 * [java/scala-compat](java/scala-compat.md)
-* [dev/index](java/dev/index.md)
 * [project/index](java/project/index.md)
 * [additional/index](java/additional/index.md)
 

akka-docs/src/main/paradox/java/io.md

@@ -101,4 +101,4 @@ A `ByteStringBuilder` can be wrapped in a `java.io.OutputStream` via the `asOutp
 
 ## Architecture in-depth
 
-For further details on the design and internal architecture see @ref:[I/O Layer Design](../scala/dev/io-layer.md).
+For further details on the design and internal architecture see @ref:[I/O Layer Design](common/io-layer.md).

akka-docs/src/main/paradox/scala.md

@@ -14,7 +14,6 @@
 * [scala/index-utilities](scala/index-utilities.md)
 * [common/other-modules](scala/common/other-modules.md)
 * [scala/howto](scala/howto.md)
-* [dev/index](scala/dev/index.md)
 * [project/index](scala/project/index.md)
 * [additional/index](scala/additional/index.md)
 

akka-docs/src/main/paradox/scala/cluster-usage.md

@@ -717,12 +717,12 @@ and to the registered subscribers on the system event bus with the help of `clus
 
 ## How to Test
 
-@ref:[Multi Node Testing](../scala/dev/multi-node-testing.md) is useful for testing cluster applications.
+@ref:[Multi Node Testing](../scala/multi-node-testing.md) is useful for testing cluster applications.
 
-Set up your project according to the instructions in @ref:[Multi Node Testing](../scala/dev/multi-node-testing.md) and @ref:[Multi JVM Testing](../scala/dev/multi-jvm-testing.md), i.e.
+Set up your project according to the instructions in @ref:[Multi Node Testing](../scala/multi-node-testing.md) and @ref:[Multi JVM Testing](../scala/multi-jvm-testing.md), i.e.
 add the `sbt-multi-jvm` plugin and the dependency to `akka-multi-node-testkit`.
 
-First, as described in @ref:[Multi Node Testing](../scala/dev/multi-node-testing.md), we need some scaffolding to configure the `MultiNodeSpec`.
+First, as described in @ref:[Multi Node Testing](../scala/multi-node-testing.md), we need some scaffolding to configure the `MultiNodeSpec`.
 Define the participating roles and their [cluster_configuration_scala](#cluster-configuration-scala) in an object extending `MultiNodeConfig`:
 
 @@snip [StatsSampleSpec.scala]($akka$/akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala) { #MultiNodeConfig }

akka-docs/src/main/paradox/scala/common/may-change.md

@@ -28,12 +28,7 @@ that the module or API wasn't useful.
 
 These are the current complete modules marked as **may change**:
 
-@@toc { depth=1 }
+* @ref:[Multi Node Testing](../../scala/multi-node-testing.md)
+* @ref:[Akka Typed](../../scala/typed.md)
 
-@@@ index
-
-* [../dev/multi-node-testing](../dev/multi-node-testing.md)
-* [../../scala/typed](../../scala/typed.md)
-
-@@@
 

akka-docs/src/main/paradox/scala/dev/building-akka.md

@@ -1,145 +0,0 @@
-# Building Akka
-
-This page describes how to build and run Akka from the latest source code.
-
-## Get the Source Code
-
-Akka uses [Git](http://git-scm.com) and is hosted at [Github](http://github.com).
-
-You first need Git installed on your machine. You can then clone the source
-repository from [http://github.com/akka/akka](http://github.com/akka/akka).
-
-For example:
-
-```
-git clone git://github.com/akka/akka.git
-```
-
-If you have already cloned the repository previously then you can update the
-code with `git pull`:
-
-```
-git pull origin master
-```
-
-## sbt
-
-Akka is using the excellent [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.
-
-The sbt commands that you'll need to build Akka are all included below. If you
-want to find out more about sbt and using it for your own projects do read the
-[sbt documentation](http://www.scala-sbt.org/documentation.html).
-
-The main Akka sbt build file is `project/AkkaBuild.scala`, with a *build.sbt* in
-each subproject’s directory. It is advisable to allocate at least 2GB of heap size
-to the JVM that runs sbt, otherwise you may experience some spurious failures when
-running the tests.
-
-## Building Akka
-
-First make sure that you are in the akka code directory:
-
-```
-cd akka
-```
-
-### Building
-
-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 compiling and testing are successful then you have everything working for the
-latest Akka development version.
-
-### Parallel Execution
-
-By default the tests are executed sequentially. They can be executed in parallel to reduce build times,
-if hardware can handle the increased memory and cpu usage. Add the following system property to sbt
-launch script to activate parallel execution:
-
-```
--Dakka.parallelExecution=true
-```
-
-### Long Running and Time Sensitive Tests
-
-By default are the long running tests (mainly cluster tests) and time sensitive tests (dependent on the
-performance of the machine it is running on) disabled. You can enable them by adding one of the flags:
-
-```
--Dakka.test.tags.include=long-running
--Dakka.test.tags.include=timing
-```
-
-Or if you need to enable them both:
-
-```
--Dakka.test.tags.include=long-running,timing
-```
-
-### Publish to Local Ivy Repository
-
-If you want to deploy the artifacts to your local Ivy repository (for example,
-to use from an sbt project) use the `publish-local` command:
-
-```
-sbt publish-local
-```
-
-### sbt Interactive Mode
-
-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
-...
-```
-
-### sbt Batch Mode
-
-It's also possible to combine commands in a single call. For example, testing,
-and publishing Akka to the local Ivy repository can be done with:
-
-```
-sbt test publish-local
-```
-
-<a id="dependencies"></a>
-## Dependencies
-
-You can look at the Ivy dependency resolution information that is created on
-`sbt update` and found in `~/.ivy2/cache`. For example, the
-`~/.ivy2/cache/com.typesafe.akka-akka-remote-compile.xml` file contains
-the resolution information for the akka-remote module compile dependencies. If
-you open this file in a web browser you will get an easy to navigate view of
-dependencies.
-
-## Scaladoc Dependencies
-
-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).

akka-docs/src/main/paradox/scala/dev/developer-guidelines.md

@@ -1,59 +0,0 @@
-# Developer Guidelines
-
-@@@ note
-
-First read [The Akka Contributor Guidelines](https://github.com/akka/akka/blob/master/CONTRIBUTING.md).
-
-@@@
-
-## Code Style
-
-The Akka code style follows the [Scala Style Guide](http://docs.scala-lang.org/style/) . The only exception is the
-style of block comments:
-
-```scala
-/**
-  * Style mandated by "Scala Style Guide"
-  */
-
-/**
- * Style adopted in the Akka codebase
- */
-```
-
-Akka is using `Scalariform` to format the source code as part of the build. So just hack away and then run `sbt compile` and it will reformat the code according to Akka standards.
-
-## Process
-
-The full process is described in [The Akka Contributor Guidelines](https://github.com/akka/akka/blob/master/CONTRIBUTING.md). In summary:
-
- * Make sure you have signed the Akka CLA, if not, [sign it online](http://www.lightbend.com/contribute/cla).
- * Pick a ticket, if there is no ticket for your work then create one first.
- * Fork [akka/akka](https://github.com/akka/akka). Start working in a feature branch.
- * When you are done, create a GitHub Pull-Request towards the targeted branch.
- * When there's consensus on the review, someone from the Akka Core Team will merge it.
-
-## Commit messages
-
-Please follow the conventions described in [The Akka Contributor Guidelines](https://github.com/akka/akka/blob/master/CONTRIBUTING.md) when creating public commits and writing commit messages.
-
-## Testing
-
-All code that is checked in **should** have tests. All testing is done with `ScalaTest` and `ScalaCheck`.
-
- * Name tests as **Test.scala** if they do not depend on any external stuff. That keeps surefire happy.
- * Name tests as **Spec.scala** if they have external dependencies.
-
-### Actor TestKit
-
-There is a useful test kit for testing actors: [akka.util.TestKit](@github@/akka-testkit/src/main/scala/akka/testkit/TestKit.scala). It enables assertions concerning replies received and their timing, there is more documentation in the <!-- FIXME: More than one link target with name akka-testkit in path Some(/dev/developer-guidelines.rst) --> akka-testkit module.
-
-### Multi-JVM Testing
-
-Included in the example is an sbt trait for multi-JVM testing which will fork
-JVMs for multi-node testing. There is support for running applications (objects
-with main methods) and running ScalaTest tests.
-
-### NetworkFailureTest
-
-You can use the 'NetworkFailureTest' trait to test network failure.

akka-docs/src/main/paradox/scala/dev/documentation.md

@@ -1,202 +0,0 @@
-# Documentation Guidelines
-
-The Akka documentation uses [reStructuredText](http://docutils.sourceforge.net/rst.html) as its markup language and is
-built using [Sphinx](http://sphinx.pocoo.org).
-
-## Sphinx
-
-For more details see [The Sphinx Documentation](http://sphinx.pocoo.org/contents.html)
-
-## reStructuredText
-
-For more details see [The reST Quickref](http://docutils.sourceforge.net/docs/user/rst/quickref.html)
-
-### Sections
-
-Section headings are very flexible in reST. We use the following convention in
-the Akka documentation:
-
- * `#` (over and under) for module headings
- * `=` for sections
- * `-` for subsections
- * `^` for subsubsections
- * `~` for subsubsubsections
-
-### Cross-referencing
-
-Sections that may be cross-referenced across the documentation should be marked
-with a reference. To mark a section use `.. _ref-name:` before the section
-heading. The section can then be linked with `:ref:`ref-name``. These are
-unique references across the entire documentation.
-
-For example:
-
-```
-.. _akka-module:
-
-#############
- Akka Module
-#############
-
-This is the module documentation.
-
-.. _akka-section:
-
-Akka Section
-============
-
-Akka Subsection
----------------
-
-Here is a reference to "akka section": :ref:`akka-section` which will have the
-name "Akka Section".
-```
-
-## Build the documentation
-
-First install [Sphinx](http://sphinx.pocoo.org). See below.
-
-### Building
-
-For the html version of the docs:
-
-```
-sbt sphinx:generateHtml
-
-open <project-dir>/akka-docs/target/sphinx/html/index.html
-```
-
-For the pdf version of the docs:
-
-```
-sbt sphinx:generatePdf
-
-open <project-dir>/akka-docs/target/sphinx/latex/AkkaJava.pdf
-or
-open <project-dir>/akka-docs/target/sphinx/latex/AkkaScala.pdf
-```
-
-### Installing Sphinx on OS X
-
-Install [Homebrew](https://github.com/mxcl/homebrew)
-
-Install Python with Homebrew:
-
-```
-brew install python
-```
-
-Homebrew will automatically add Python executable to your $PATH and pip is a part of the default Python installation with Homebrew.
-
-More information in case of trouble:
-[https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python)
-
-Install sphinx:
-
-```
-pip install sphinx
-```
-
-Install BasicTeX package from:
-[http://www.tug.org/mactex/morepackages.html](http://www.tug.org/mactex/morepackages.html)
-
-Add texlive bin to $PATH:
-
-```
-export TEXLIVE_PATH=/usr/local/texlive/2016basic/bin/universal-darwin
-export PATH=$TEXLIVE_PATH:$PATH
-```
-
-Add missing tex packages:
-
-```
-sudo tlmgr update --self
-sudo tlmgr install titlesec
-sudo tlmgr install framed
-sudo tlmgr install threeparttable
-sudo tlmgr install wrapfig
-sudo tlmgr install helvetic
-sudo tlmgr install courier
-sudo tlmgr install multirow
-sudo tlmgr install capt-of
-sudo tlmgr install needspace
-sudo tlmgr install eqparbox
-sudo tlmgr install environ
-sudo tlmgr install trimspaces
-```
-
-If you get the error "unknown locale: UTF-8" when generating the documentation the solution is to define the following environment variables:
-
-```
-export LANG=en_US.UTF-8
-export LC_ALL=en_US.UTF-8
-```
-
-### Installing Sphinx on Linux
-
-Install Python with your package manager:
-
-```
-apt-get install python # for Debian based systems
-yum install python     # for CentOS/RHEL systems
-```
-
-This will automatically add Python executable to your $PATH and pip is a part of the default Python installation. Remember you need *sudo* rights to run this command.
-
-More information in case of trouble:
-[https://packaging.python.org/install_requirements_linux](https://packaging.python.org/install_requirements_linux)/ 
-
-Install Sphinx:
-
-```
-apt-get install python-sphinx # for Debian based systems
-#alternatively
-pip install sphinx
-```
-
-For other Linux systems please check Sphinx website:
-[http://www.sphinx-doc.org/en/stable/install.html#other-linux-distributions](http://www.sphinx-doc.org/en/stable/install.html#other-linux-distributions)
-
-Install TextLive:
-
-```
-apt-get install texlive-latex-base texlive-latex-extra texlive-latex-recommended
-# additionally you may need xzdec
-apt-get install xzdec
-```
-
-In case you get the following error:
-
->
-Unknown directive ...containerchecksum c59200574a316416a23695c258edf3a32531fbda43ccdc09360ee105c3f07f9fb77df17c4ba4c2ea4f3a5ea6667e064b51e3d8c2fe6c984ba3e71b4e32716955... , please fix it! at /usr/share/texlive/tlpkg/TeXLive/TLPOBJ.pm line 210, <$retfh> line 5579.
-
-you need to specify you want to continue using the 2015 version:
-
-```
-tlmgr option repository ftp://tug.org/historic/systems/texlive/2015/tlnet-final
-```
-
-Add missing tex packages:
-
-```
-sudo tlmgr update --self
-sudo tlmgr install titlesec
-sudo tlmgr install framed
-sudo tlmgr install threeparttable
-sudo tlmgr install wrapfig
-sudo tlmgr install helvetic
-sudo tlmgr install courier
-sudo tlmgr install multirow
-sudo tlmgr install capt-of
-sudo tlmgr install needspace
-sudo tlmgr install eqparbox
-sudo tlmgr install environ
-sudo tlmgr install trimspaces
-```
-
-If you get the error "unknown locale: UTF-8" when generating the documentation the solution is to define the following environment variables:
-
-```
-export LANG=en_US.UTF-8
-export LC_ALL=en_US.UTF-8
-```

akka-docs/src/main/paradox/scala/dev/index.md

@@ -1,13 +0,0 @@
-# Information for Akka Developers
-
-@@toc { depth=2 }
-
-@@@ index
-
-* [building-akka](building-akka.md)
-* [multi-jvm-testing](multi-jvm-testing.md)
-* [io-layer](io-layer.md)
-* [developer-guidelines](developer-guidelines.md)
-* [documentation](documentation.md)
-
-@@@

akka-docs/src/main/paradox/scala/index-network.md

@@ -19,5 +19,6 @@
 * [io-tcp](io-tcp.md)
 * [io-udp](io-udp.md)
 * [camel](camel.md)
+* [multi-jvm-testing](multi-jvm-testing.md)
 
 @@@

akka-docs/src/main/paradox/scala/io.md

@@ -101,4 +101,4 @@ A `ByteStringBuilder` can be wrapped in a `java.io.OutputStream` via the `asOutp
 
 ## Architecture in-depth
 
-For further details on the design and internal architecture see @ref:[I/O Layer Design](../scala/dev/io-layer.md).
+For further details on the design and internal architecture see @ref:[I/O Layer Design](common/io-layer.md).

akka-docs/src/main/paradox/scala/multi-jvm-testing.md

@@ -196,5 +196,5 @@ the sbt prompt.
 ## Multi Node Additions
 
 There has also been some additions made to the `SbtMultiJvm` plugin to accommodate the
-@ref:[may change](../common/may-change.md) module @ref:[multi node testing](multi-node-testing.md),
+@ref:[may change](common/may-change.md) module @ref:[multi node testing](multi-node-testing.md),
 described in that section.

akka-docs/src/main/paradox/scala/multi-node-testing.md

@@ -198,4 +198,4 @@ thread. This also means that you shouldn't use them from inside an actor, a futu
 ## Configuration
 
 There are several configuration properties for the Multi-Node Testing module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-multi-node-testkit).
+to the @ref:[reference configuration](general/configuration.md#config-akka-multi-node-testkit).