fixes based on review comments
This commit is contained in:
Roland
Björn Antonsson
parent
cc669c3838
commit
323e2c04ff
7 changed files with 75 additions and 113 deletions
|
|
@ -59,8 +59,10 @@ Akka uses [Scalariform](https://github.com/mdr/scalariform) to enforce some of t
|
|||
|
||||
##Contributing Modules##
|
||||
|
||||
For external contributions of entire modules, the normal way is to establish it as a stand-alone module first,
|
||||
to show that there is a need for the module. The next step would be to add it to Akka as an "experimental module" (in the akka-contrib subproject),
|
||||
then when the module is hardened, well documented and tested it becomes an officially supported Akka module.
|
||||
For external contributions of entire features, the normal way is to establish it
|
||||
as a stand-alone feature first, to show that there is a need for the feature. The
|
||||
next step would be to add it to Akka as an "experimental feature" (in the
|
||||
akka-contrib subproject), then when the feature is hardened, well documented and
|
||||
tested it becomes an officially supported Akka feature.
|
||||
|
||||
[List of experimental Akka modules](http://doc.akka.io/docs/akka/current/experimental/index.html)
|
||||
[List of experimental Akka features](http://doc.akka.io/docs/akka/current/experimental/index.html)
|
||||
|
|
|
|||
|
|
@ -1,25 +1,52 @@
|
|||
# External Contributions
|
||||
|
||||
This subproject provides a home to modules contributed by external developers which may or may not move into the officially supported code base over time. The conditions under which this transition can occur include:
|
||||
This subproject provides a home to modules contributed by external developers
|
||||
which may or may not move into the officially supported code base over time.
|
||||
The conditions under which this transition can occur include:
|
||||
|
||||
* there must be enough interest in the module to warrant inclusion in the standard distribution,
|
||||
* the module must be actively maintained and
|
||||
* code quality must be good enough to allow efficient maintenance by the Akka core development team
|
||||
|
||||
If a contributions turns out to not “take off” it may be removed again at a later time.
|
||||
If a contributions turns out to not “take off” it may be removed again at a
|
||||
later time.
|
||||
|
||||
## Caveat Emptor
|
||||
|
||||
A module in this subproject doesn't have to obey the rule of staying binary compatible between minor releases. Breaking API changes may be introduced in minor releases without notice as we refine and simplify based on your feedback. A module may be dropped in any release without prior deprecation. The Typesafe subscription does not cover support for these modules.
|
||||
A module in this subproject doesn't have to obey the rule of staying binary
|
||||
compatible between micro releases. Breaking API changes may be introduced in
|
||||
minor releases without notice as we refine and simplify based on your feedback.
|
||||
A module may be dropped in any release without prior deprecation. The Typesafe
|
||||
subscription does not cover support for these modules.
|
||||
|
||||
## Suggested Format of Contributions
|
||||
|
||||
Each contribution should be a self-contained unit, consisting of one source file or one exclusively used package, without dependencies to other modules in this subproject; it may depend on everything else in the Akka distribution, though. This ensures that contributions may be moved into the standard distribution individually. The module shall be within a subpackage of `akka.contrib`.
|
||||
Each contribution should be a self-contained unit, consisting of one source
|
||||
file or one exclusively used package, without dependencies to other modules in
|
||||
this subproject; it may depend on everything else in the Akka distribution,
|
||||
though. This ensures that contributions may be moved into the standard
|
||||
distribution individually. The module shall be within a subpackage of
|
||||
`akka.contrib`.
|
||||
|
||||
Each module must be accompanied by a test suite which verifies that the provided features work, possibly complemented by integration and unit tests. The tests should follow the [Developer Guidelines](http://doc.akka.io/docs/akka/current/dev/developer-guidelines.html#testing) and go into the `src/test/scala` or `src/test/java` directories (with package name matching the module which is being tested). As an example, if the module were called `akka.contrib.pattern.ReliableProxy`, then the test suite should be called `akka.contrib.pattern.ReliableProxySpec`.
|
||||
Each module must be accompanied by a test suite which verifies that the
|
||||
provided features work, possibly complemented by integration and unit tests.
|
||||
The tests should follow the [Developer
|
||||
Guidelines](http://doc.akka.io/docs/akka/current/dev/developer-guidelines.html#testing)
|
||||
and go into the `src/test/scala` or `src/test/java` directories (with package
|
||||
name matching the module which is being tested). As an example, if the module
|
||||
were called `akka.contrib.pattern.ReliableProxy`, then the test suite should be
|
||||
called `akka.contrib.pattern.ReliableProxySpec`.
|
||||
|
||||
Each module must also have proper documentation in [reStructured Text format](http://sphinx.pocoo.org/rest.html). The documentation should be a single `<module>.rst` file in the `akka-contrib/docs` directory, including a link from `index.rst`.
|
||||
Each module must also have proper documentation in [reStructured Text
|
||||
format](http://sphinx.pocoo.org/rest.html). The documentation should be a
|
||||
single `<module>.rst` file in the `akka-contrib/docs` directory, including a
|
||||
link from `index.rst`.
|
||||
|
||||
## Suggested Way of Using these Contributions
|
||||
|
||||
Since the Akka team does not restrict updates to this subproject even during otherwise binary compatible releases, and modules may be removed without deprecation, it is suggested to copy the source files into your own code base, changing the package name. This way you can choose when to update or which fixes to include (to keep binary compatibility if needed) and later releases of Akka do not potentially break your application.
|
||||
Since the Akka team does not restrict updates to this subproject even during
|
||||
otherwise binary compatible releases, and modules may be removed without
|
||||
deprecation, it is suggested to copy the source files into your own code base,
|
||||
changing the package name. This way you can choose when to update or which
|
||||
fixes to include (to keep binary compatibility if needed) and later releases of
|
||||
Akka do not potentially break your application.
|
||||
|
|
|
|||
|
|
@ -1,85 +0,0 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# Akka documentation build configuration file.
|
||||
#
|
||||
|
||||
import sys, os
|
||||
|
||||
# -- General configuration -----------------------------------------------------
|
||||
|
||||
sys.path.append(os.path.abspath('../../akka-docs/_sphinx/exts'))
|
||||
extensions = ['sphinx.ext.todo', 'includecode']
|
||||
|
||||
templates_path = ['_templates']
|
||||
source_suffix = '.rst'
|
||||
master_doc = 'index'
|
||||
exclude_patterns = ['_build', 'pending', 'disabled']
|
||||
|
||||
project = u'Akka'
|
||||
copyright = u'2011, Typesafe Inc'
|
||||
version = '@version@'
|
||||
release = '@version@'
|
||||
|
||||
pygments_style = 'simple'
|
||||
highlight_language = 'scala'
|
||||
add_function_parentheses = False
|
||||
show_authors = True
|
||||
|
||||
# -- Options for HTML output ---------------------------------------------------
|
||||
|
||||
html_theme = 'akka'
|
||||
html_theme_path = ['../../akka-docs/_sphinx/themes']
|
||||
html_favicon = '../../akka-docs/_sphinx/static/favicon.ico'
|
||||
|
||||
html_title = 'Akka Documentation'
|
||||
html_logo = '../../akka-docs/_sphinx/static/logo.png'
|
||||
#html_favicon = None
|
||||
|
||||
html_static_path = ['../../akka-docs/_sphinx/static']
|
||||
|
||||
html_last_updated_fmt = '%b %d, %Y'
|
||||
#html_sidebars = {}
|
||||
#html_additional_pages = {}
|
||||
html_domain_indices = False
|
||||
html_use_index = False
|
||||
html_show_sourcelink = False
|
||||
html_show_sphinx = False
|
||||
html_show_copyright = True
|
||||
htmlhelp_basename = 'Akkadoc'
|
||||
html_use_smartypants = False
|
||||
html_add_permalinks = ''
|
||||
|
||||
html_context = {
|
||||
'include_analytics': 'online' in tags
|
||||
}
|
||||
|
||||
# -- Options for EPUB output ---------------------------------------------------
|
||||
epub_author = "Typesafe Inc"
|
||||
epub_language = "en"
|
||||
epub_publisher = epub_author
|
||||
epub_identifier = "http://doc.akka.io/docs/akka/snapshot/"
|
||||
epub_scheme = "URL"
|
||||
epub_cover = ("../../akka-docs/_sphinx/static/akka.png", "")
|
||||
|
||||
# -- Options for LaTeX output --------------------------------------------------
|
||||
|
||||
def setup(app):
|
||||
from sphinx.util.texescape import tex_replacements
|
||||
tex_replacements.append((u'⇒', ur'\(\Rightarrow\)'))
|
||||
|
||||
latex_paper_size = 'a4'
|
||||
latex_font_size = '10pt'
|
||||
|
||||
latex_documents = [
|
||||
('index', 'Akka.tex', u' Akka Documentation',
|
||||
u'Typesafe Inc', 'manual'),
|
||||
]
|
||||
|
||||
latex_elements = {
|
||||
'classoptions': ',oneside,openany',
|
||||
'babel': '\\usepackage[english]{babel}',
|
||||
'fontpkg': '\\PassOptionsToPackage{warn}{textcomp} \\usepackage{times}',
|
||||
'preamble': '\\definecolor{VerbatimColor}{rgb}{0.935,0.935,0.935}'
|
||||
}
|
||||
|
||||
# latex_logo = '_sphinx/static/akka.png'
|
||||
|
|
@ -90,3 +90,32 @@ From Scala it would look like so:
|
|||
.. includecode:: @contribSrc@/src/test/scala/akka/contrib/pattern/ReliableProxyDocSpec.scala#demo-transition
|
||||
|
||||
|
||||
The Actor Contract
|
||||
------------------
|
||||
|
||||
Message it Processes
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* :class:`FSM.SubscribeTransitionCallBack` and :class:`FSM.UnsubscribeTransitionCallBack`, see :ref:`fsm-scala`
|
||||
* internal messages declared within :obj:`ReliableProxy`, *not for external use*
|
||||
* any other message is transferred through the reliable tunnel and forwarded to the designated target actor
|
||||
|
||||
Messages it Sends
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
* :class:`FSM.CurrentState` and :class:`FSM.Transition`, see :ref:`fsm-scala`
|
||||
|
||||
Exceptions it Escalates
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* no specific exception types
|
||||
* any exception encountered by either the local or remote end-point are escalated (only fatal VM errors)
|
||||
|
||||
Arguments it Takes
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* *target* is the :class:`ActorRef` to which the tunnel shall reliably deliver
|
||||
messages, ``B`` in the above illustration.
|
||||
* *retryAfter* is the timeout for receiving ACK messages from the remote
|
||||
end-point; once it fires, all outstanding message sends will be retried.
|
||||
|
||||
|
|
|
|||
|
|
@ -50,8 +50,6 @@ public class ReliableProxyTest {
|
|||
//#demo-proxy
|
||||
final ActorRef proxy = getContext().actorOf(
|
||||
new Props(new UntypedActorFactory() {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public Actor create() {
|
||||
final FiniteDuration retry = Duration.create(100, "millis");
|
||||
return new ReliableProxy(target, retry);
|
||||
|
|
@ -83,8 +81,6 @@ public class ReliableProxyTest {
|
|||
//#demo-transition
|
||||
final ActorRef proxy = getContext().actorOf(
|
||||
new Props(new UntypedActorFactory() {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public Actor create() {
|
||||
final FiniteDuration retry = Duration.create(100, "millis");
|
||||
return new ReliableProxy(target, retry);
|
||||
|
|
|
|||
|
|
@ -11,9 +11,9 @@ experimental, is to make them easily available and improve based on
|
|||
feedback, or even discover that the module wasn't useful.
|
||||
|
||||
An experimental module doesn't have to obey the rule of staying binary
|
||||
compatible between minor releases. Breaking API changes may be introduced
|
||||
compatible between micro releases. Breaking API changes may be introduced
|
||||
in minor releases without notice as we refine and simplify based on your
|
||||
feedback. An experimental module may be dropped in major releases without
|
||||
feedback. An experimental module may be dropped in minor releases without
|
||||
prior deprecation.
|
||||
|
||||
.. toctree::
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ object AkkaBuild extends Build {
|
|||
generatePdf in Sphinx <<= generatePdf in Sphinx in LocalProject(docs.id) map identity
|
||||
|
||||
),
|
||||
aggregate = Seq(actor, testkit, actorTests, dataflow, remote, remoteTests, camel, cluster, slf4j, agent, transactor, mailboxes, zeroMQ, kernel, akkaSbtPlugin, osgi, osgiAries, docs)
|
||||
aggregate = Seq(actor, testkit, actorTests, dataflow, remote, remoteTests, camel, cluster, slf4j, agent, transactor, mailboxes, zeroMQ, kernel, akkaSbtPlugin, osgi, osgiAries, docs, contrib)
|
||||
)
|
||||
|
||||
lazy val actor = Project(
|
||||
|
|
@ -356,14 +356,14 @@ object AkkaBuild extends Build {
|
|||
sphinxPackages in Sphinx <+= baseDirectory { _ / "_sphinx" / "pygments" },
|
||||
// copy akka-contrib/docs into our rst_preprocess/contrib (and apply substitutions)
|
||||
preprocess in Sphinx <<= (preprocess in Sphinx,
|
||||
sourceDirectory in contrib in Sphinx,
|
||||
baseDirectory in contrib,
|
||||
target in preprocess in Sphinx,
|
||||
cacheDirectory,
|
||||
preprocessExts in Sphinx,
|
||||
preprocessVars in Sphinx,
|
||||
streams) map { (orig, src, target, cacheDir, exts, vars, s) =>
|
||||
val contribSrc = Map("contribSrc" -> "../../../akka-contrib")
|
||||
simplePreprocess(src, target / "contrib", cacheDir / "sphinx" / "preprocessed-contrib", exts, vars ++ contribSrc, s.log)
|
||||
simplePreprocess(src / "docs", target / "contrib", cacheDir / "sphinx" / "preprocessed-contrib", exts, vars ++ contribSrc, s.log)
|
||||
orig
|
||||
},
|
||||
enableOutput in generatePdf in Sphinx := true,
|
||||
|
|
@ -378,16 +378,9 @@ object AkkaBuild extends Build {
|
|||
id = "akka-contrib",
|
||||
base = file("akka-contrib"),
|
||||
dependencies = Seq(remote, remoteTests % "compile;test->test"),
|
||||
settings = defaultSettings ++ multiJvmSettings ++ SphinxSupport.settings ++ sphinxPreprocessing ++ Seq(
|
||||
settings = defaultSettings ++ multiJvmSettings ++ Seq(
|
||||
libraryDependencies ++= Dependencies.contrib,
|
||||
testOptions += Tests.Argument(TestFrameworks.JUnit, "-v"),
|
||||
preprocessVars in Sphinx <<= (preprocessVars in Sphinx) { (old) =>
|
||||
old ++ Map(
|
||||
"contribSrc" -> ".."
|
||||
)
|
||||
},
|
||||
sourceDirectory in Sphinx <<= baseDirectory / "docs",
|
||||
sphinxPackages in Sphinx <+= baseDirectory { _ / ".." / "akka-docs" / "_sphinx" / "pygments" },
|
||||
description := """|
|
||||
|This subproject provides a home to modules contributed by external
|
||||
|developers which may or may not move into the officially supported code
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue