This is an automated email from the ASF dual-hosted git repository.

dgrove pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk.git


The following commit(s) were added to refs/heads/master by this push:
     new 229b0c0  Cleanup/organize instructions for adding a new Action Runtime 
(#4099)
229b0c0 is described below

commit 229b0c0eeaf4304583f0c744d04a58e199927694
Author: Matt Rutkowski <mrutk...@us.ibm.com>
AuthorDate: Fri Dec 7 07:42:04 2018 -0600

    Cleanup/organize instructions for adding a new Action Runtime (#4099)
---
 docs/actions-new.md | 104 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 62 insertions(+), 42 deletions(-)

diff --git a/docs/actions-new.md b/docs/actions-new.md
index 91704d7..3e9a86d 100644
--- a/docs/actions-new.md
+++ b/docs/actions-new.md
@@ -16,6 +16,7 @@
 # limitations under the License.
 #
 -->
+## Adding Action Language Runtimes
 
 OpenWhisk supports [several languages and 
runtimes](actions.md#languages-and-runtimes) but
 there may be other languages or runtimes that are important for your 
organization, and for
@@ -23,34 +24,42 @@ which you want tighter integration with the platform. The 
OpenWhisk platform is
 and you can add new languages or runtimes (with custom packages and 
third-party dependencies)
 following the guide described here.
 
-### Unit of execution
-The unit of execution for all functions is a [Docker 
container](https://docs.docker.com).
-The container implements a specific interface which:
-1. accepts an initialization payload (the code) and prepared for execution,
-2. accepts runtime payload (the input parameters) and
+### Runtime general requirements
+
+The unit of execution for all functions is a [Docker 
container](https://docs.docker.com) which
+must implement a specific [Action interface](#action-interface) that, in 
general performs:
+
+1. **[Initialization](#initialization)** - accepts an initialization payload 
(the code) and prepared for execution,
+2. **[Activation](#activation)** - accepts a runtime payload (the input 
parameters) and
    - prepares the activation context,
    - runs the function,
    - returns the function result,
-3. flushes all `stdout` and `stderr` logs and adds a frame marker at the end 
of the activation.
+3. **[Logging](#logging)** - flushes all `stdout` and `stderr` logs and adds a 
frame marker at the end of the activation.
+
+The specifics of the [Action interface](#action-interface) and its functions 
are shown below.
 
-Any container which implements [the interface](#action-interface) may be used 
as an action.
-It is in this way that you can add support for other languages or customized 
runtimes.
+### Platform requirements
 
-The interface is enforced via a [canonical test 
suite](../tests/src/test/scala/actionContainers/BasicActionRunnerTests.scala)
-which validates the initialization protocol, the runtime protocol, ensures the 
activation context is correctly prepared,
-and that the logs are properly framed. Your runtime should extend this test 
suite, and of course include additional tests
-as needed.
+In order for your language runtime to be properly recognized by the OpenWhisk 
platform, the following additional requirments must be fulfilled:
 
-The runtime support is best implemented in its own repository to permit a 
management
-lifecycle independent of the rest of the OpenWhisk platform which requires the 
following
-additions:
 1. introduce the runtime specification into the [runtimes 
manifest](../ansible/files/runtimes.json),
-2. add a new `actions-<your runtime>.md` file to the [docs](.) directory,
-3. add a link to your new language or runtime to the [top level 
index](actions.md#languages-and-runtimes),
-4. add the runtime to the [Swagger 
file](../core/controller/src/main/resources/apiv1swagger.json),
-5. add a standard test action to the [tests artifacts 
directory](../tests/dat/actions/unicode.tests).
+2. add the runtime to the [Swagger 
file](../core/controller/src/main/resources/apiv1swagger.json)
+
+### Project requirements
+
+If you wish to have your runtime officially recognized by the Apache OpenWhisk 
project, please follow these
+additional rqeuirements and best practices:
+
+1. implement the runtime in its own repository to permit a management 
lifecycle independent of the rest of the OpenWhisk platform,
+    - The repository should conform to the [Canonical runtime 
repository](#canonical-runtime-repository) layout (as shown below).
+2. add a standard [test action](#the-test-action) to the [tests artifacts 
directory](../tests/dat/actions/unicode.tests) (as shown below),
+3. automate and pass the following test suites:
+    - [Action Interface tests](#action-interface-tests)
+    - [Runtime proxy tests](#runtime-proxy-tests)
+4. add a new `actions-<your runtime>.md` file to the [docs](.) directory,
+5. add a link to your new language or runtime to the [top level 
index](actions.md#languages-and-runtimes).
 
-### The runtime manifest
+### The runtimes manifest
 
 Actions when created specify the desired runtime for the function via a 
property called "kind".
 When using the `wsk` CLI, this is specified as `--kind <runtime-kind>`. The 
value is a typically
@@ -77,25 +86,9 @@ As an example, the following entry add a new runtime family 
called `nodejs` with
 ```
 
 The `default` property indicates if the corresponding kind should be treated 
as the
-default for the runtime family. The `image` structure defines the Docker image 
name
-that is used for actions of this kind (e.g., `openwhisk/nodejs6action:latest` 
here).
-
-### The test action
-
-The standard test action is shown below in JavaScript. It should be adapted 
for the
-new language and added to the [test artifacts 
directory](../tests/dat/actions/unicode.tests)
-with the name `<runtime-kind>.txt` for plain text file or `<runtime-kind>.bin` 
for a
-a binary file. The `<runtime-kind>` must match the value used for `kind` in 
the corresponding
-runtime manifest entry, replacing `:` in the kind with a `-`.
-For example, a plain text function for `nodejs:8` becomes `nodejs-8.txt`.
-
-```js
-function main(args) {
-    var str = args.delimiter + " ☃ " + args.delimiter;
-    console.log(str);
-    return { "winter": str };
-}
-```
+default for the runtime family. The JSON `image` structure defines the Docker 
image name
+that is used for actions of this kind (e.g., `openwhisk/nodejs6action:latest` 
for the
+JSON example above).
 
 ### Canonical runtime repository
 
@@ -116,6 +109,23 @@ The runtime repository should follow the canonical 
structure used by other runti
 The [Docker skeleton 
repository](https://github.com/apache/incubator-openwhisk-runtime-docker)
 is an example starting point to fork and modify for your new runtime.
 
+#### The test action
+
+The standard test action is shown below in JavaScript. It should be adapted 
for the
+new language and added to the [test artifacts 
directory](../tests/dat/actions/unicode.tests)
+with the name `<runtime-kind>.txt` for plain text file or `<runtime-kind>.bin` 
for a
+a binary file. The `<runtime-kind>` must match the value used for `kind` in 
the corresponding
+runtime manifest entry, replacing `:` in the kind with a `-`.
+For example, a plain text function for `nodejs:8` becomes `nodejs-8.txt`.
+
+```js
+function main(args) {
+    var str = args.delimiter + " ☃ " + args.delimiter;
+    console.log(str);
+    return { "winter": str };
+}
+```
+
 ### Action Interface
 
 An action consists of the user function (and its dependencies) along with a 
_proxy_ that implements a
@@ -221,7 +231,7 @@ which is "application error" if the proxy returned an 
"error" object, and "actio
 must complete within the allowed duration. Failure to complete activation 
within the allowed time frame
 will destroy the container.
 
-#### Logs
+#### Logging
 
 The proxy must flush all the logs produced during initialization and execution 
and add a frame marker
 to denote the end of the log stream for an activation. This is done by 
emitting the token
@@ -229,10 +239,20 @@ to denote the end of the log stream for an activation. 
This is done by emitting
 as the last log line for the `stdout` _and_ `stderr` streams. Failure to emit 
this marker will cause delayed
 or truncated activation logs.
 
-### Testing the new runtime
+### Testing
+
+#### Action Interface tests
+
+The [Action interface](#action-interface) is enforced via a [canonical test 
suite](../tests/src/test/scala/actionContainers/BasicActionRunnerTests.scala) 
which validates the initialization protocol, the runtime protocol,
+ensures the activation context is correctly prepared, and that the logs are 
properly framed. Your
+runtime should extend this test suite, and of course include additional tests 
as needed.
+
+#### Runtime proxy tests
 
 There is a [canonical test 
harness](../tests/src/test/scala/actionContainers/BasicActionRunnerTests.scala)
-for validating a new runtime. The harness will performing the following:
+for validating a new runtime.
+
+The harness will performing the following:
 * Test the proxy can handle the identity functions (initialize and run).
 * Test the proxy can properly handle functions with Unicode characters.
 * Test the proxy properly constructs the activation context.

Reply via email to