Documentation Update of 2020.01

We have been progressed a lot. Update the documentation accordingly.

V2: fixed typos

Signed-off-by: MyungJoo Ham <myungjoo.ham@samsung.com>

diff --git a/Documentation/coding-convention.md b/Documentation/coding-convention.md
index 01be875..a195cfe 100644 (file)
--- a/Documentation/coding-convention.md
+++ b/Documentation/coding-convention.md
@@ -1,12 +1,13 @@
 
 # Coding Convention
 
-NNStreamer Application follows [The Coding Style of GStreamer](https://gstreamer.freedesktop.org/documentation/frequently-asked-questions/developing.html#what-is-the-coding-style-for-gstreamer-code) for coding convention. 
+In general, NNStreamer Application follows [The Coding Style of GStreamer](https://gstreamer.freedesktop.org/documentation/frequently-asked-questions/developing.html#what-is-the-coding-style-for-gstreamer-code) for coding convention.
 
+## C codes (.c sources)
 
-Basically, the core and almost all plugin modules use K&R with 2-space indenting. Just follow what's already there and you'll be fine. We only require code files to be indented, header may be indented manually for better readability. Please use spaces for indenting, not tabs, even in header files.
+All C codes of NNStreamer are required to use K&R with 2-space indenting. Just follow what's already there and you'll be fine. We only require .c files to be indented, headers may be indented differently for better readability. Please use spaces for indenting, not tabs, even in header files.
 
-When you push your commits, ALWAYS run `gst-indent` to submit a commit with style change.
+When you push your commits, apply `gst-indent` to .c files before you submit a commit with style change.
 If there is a change due to code style issues, make two separate commits: (Please do not include other codes' style change in the same commit)
 - commit with style change only (i.e., commit gst-indent-formatted original code - not your code change)
 - commit with your code change only (i.e., contents only).
@@ -14,3 +15,65 @@ If there is a change due to code style issues, make two separate commits: (Pleas
 ```
 $ ./tools/development/gst-indent <file-name>
 ```
+
+## C headers (.h)
+
+You may indent differently from what gst-indent does. You may also break the 80-column rule with header files.
+
+Except the two, you are required to follow the general coding styles mandated by gst-indent
+
+## C++ files (.cc)
+
+Do not use .cpp extensions, use .cc extensions for C++ sources. Use .h for headers.
+
+We do not have strict rules on C++ sources, yet, because all the cores are written in C.
+However, please try to stick with the same indentation rules (2 spaces) and common senses.
+
+## Other files
+
+- [Java] TBD
+- [Python] TBD
+- [Bash] TBD
+
+
+# File Locations
+
+## Directory structure of nnstreamer.git
+
+- **api**: API definitions and implementations
+    - **android**: Android APIs
+    - **capi**: C-APIs (Tizen and others)
+    - Note that .NET APIs are located at https://github.com/Samsung/TizenFX along with other Tizen .NET APIs
+- **debian**: Debian/Ubuntu packaging files
+- **Documentation**: Documentations
+- **ext/nnstreamer**: NNStreamer plugins and subplugins that depend on optional or non-standard external packages. Components in this directory can be built and included optionally.
+    - **android\_source**: Plugins required to support Android/JAVA APIs.
+    - **tensor\_decoder**: Decoder subplugins
+    - **tensor\_filter**: Filter subplugins
+    - **tensor\_source**: Source elements that provide tensor/tensors streams. We do not have subplugin architectures for sources.
+    - Potentially we can add **tensor\_converter** here later for converter subplugins. We do not have converter subplugins released, yet.
+- **gst/nnstreamer**: All core nnstreamer codes are located here.
+    - **tensor\_\* **: Plugins of nnstreamer.
+- **jni**: Android/Java build scripts.
+- **nnstreamer\_example**: Example custom filters required by test cases. In the old days, we used to have all nnstreamer examples here. Most of such examples are moved to [Example git](https://github.com/nnsuite/nnstreamer-example) except for those who required by test cases.
+- **packaging**: Tizen RPM build scripts. OpenSUSE/Redhat Linux may reuse this.
+- **tests**: Unit test cases. We have SSAT test cases and GTEST test cases. There are a lot of subdirectories, which are groups of unit test cases.
+- **tools**: Various developmental tools and scripts of NNStreamer.
+
+## Related git repositories in nnsuite
+
+- [NNStreamer Examplie Applications \& Documents](https://github.com/nnsuite/nnstreamer-example)
+- [TAOS-CI, CI Service for On-Device AI Systems](https://github.com/nnsuite/TAOS-CI)
+- [NNStreamer ROS (Robot OS) Support](https://github.com/nnsuite/nnstreamer-ros)
+- [NNStreamer Android Build Resource](https://github.com/nnsuite/nnstreamer-android-resource): additional files required by Android builds.
+- [ORC, aarch64 support](https://github.com/nnsuite/orc): we are going to support aarch64-ORC to accelerate transform operations of nnstreamer in aarch64 devices.
+- [NNStreamer-Edge](https://github.com/nnsuite/nnstreamer-edge): WIP
+- [NNStreamer Yocto/OpenEmbedded Layer](https://github.com/nnsuite/meta-neural-network): refer to [Openembedded layer page](https://layers.openembedded.org/layerindex/branch/master/layer/meta-neural-network/)
+- [NNStreamer/NNSuite Web Page](https://github.com/nnsuite/nnsuite.github.io): WIP
+- **tizenport-\* **: Tizen-ROS support. Refer to [build.tizen.org](https://build.tizen.org/project/show/devel:AIC:Tizen:5.0:nnsuite)
+
+
+
+## Related external git repositories
+
+- [NNStreamer mirror in Tizen.org](https://git.tizen.org/cgit/platform/upstream/nnstreamer/)

diff --git a/Documentation/component-description.md b/Documentation/component-description.md
index 5d16ebf..1c64da1 100644 (file)
--- a/Documentation/component-description.md
+++ b/Documentation/component-description.md
@@ -2,13 +2,13 @@
 
 - other/tensor
 - other/tensors
-- other/tensorsave (Planned)
+- other/tensorsave (planned --> canceled)
 
-findtype specifics: refer to the wiki ([other/tensorsave](https://github.com/nnsuite/nnstreamer/wiki/Design-External-Save-Format-for-other-tensor-and-other-tensors-Stream-for-TypeFind))
+The findtype specifics: refer to the wiki ([other/tensorsave (canceled)](https://github.com/nnsuite/nnstreamer/wiki/Design-External-Save-Format-for-other-tensor-and-other-tensors-Stream-for-TypeFind))
 
-Note that in any frame in a stream of other/tensor and other/tensors, there should be only ONE instance of other/tensor or other/tensors.
+Each frame of an other/tensor or other/tensors stream should have only ONE instance of other/tensor or other/tensors.
 
-Note that except for tensor\_decoder, which accepts data semantics from pipeline developers, and tensor\_converter, which accepts data semantics from sink pad caps, any NNStreamer tensor plugins or any instances of tensor streams should be agnostic to the data semantics. With data semantics, we know whether the corresponding tensor denotes for video, audio, text, or any other "meaningful data types". The NNStreamer elements and data-pipeline should treat every other/tensor and other/tensors as arrays of numbers only.
+Except tensor\_decoder, which accepts data semantics from pipeline developers, and tensor\_converter, which accepts data semantics from sink pad caps, every NNStreamer tensor plugin and tensor stream should be agnostic to the data semantics. With data semantics, we know whether the corresponding tensor denotes for video, audio, text, or any other "meaningful data types". The NNStreamer elements and data-pipeline, being agnostic to such semantics, should treat every other/tensor and other/tensors as multi-dimensional arrays of general numbers.
 
 # Gstreamer Elements (Plugins)
 
@@ -26,6 +26,8 @@ In this page, we focus on the status of each elements. For requirements and desi
     - text/x-raw. Users should specify the byte size of a single tensor frame with the property ```input-dim```. Needs more test cases.
   - Binary (stable)
     - application/octet-stream. Stream pipeline developer MUST specify the corresponding type and dimensions via properties (input-dim, input-type)
+  - You may add subplugins of converters. However, as of 2020-01-10, we do not have any converter subplugins released although we do support them. Users may add such subplugins in run-time.
+    - Planned: flatbuffers, protobuf
 - [tensor\_filter](../gst/nnstreamer/tensor_filter)
   - Main (stable)
     - Supported features
@@ -34,20 +36,23 @@ In this page, we focus on the status of each elements. For requirements and desi
       - Invoke subplugin with pre-allocated buffers
       - Invoke subplugin and let subplugin allocate output buffers.
       - Accept other/tensors.
+      - Users can add plugins in run-time.
     - TODO: Allow to manage synchronization policies.
   - Custom-C (stable)
-  - Custom-C++-Class (stable)
-  - Custom-C-Easy (stable) (single function ops)
-  - Custom-Python (stable)
+  - Custom-C++-Class (WIP)
+  - Custom-C-Easy (stable) (single function ops. basis for lambda functions in the future)
+  - Custom-Python (stable) (2.7 and 3)
   - Custom Native Functions (stable) (Supply custom-filter in run-time)
-  - Tensorflow (stable)
-  - Tensorflow-lite (stable)
+  - Tensorflow (stable) (1.09, 1.13 tested)
+  - Tensorflow-lite (stable) (1.09, 1.13 tested)
   - Caffe2 (stable)
   - PyTorch (stable)
   - Movidius-X NCS2 (stable)
-  - NNFW-Runtime (stable)
-  - WIP: edge-TPU, openVINO(dldt), and a few more
-  - Other NNFW TBD (keras, caffe, Exynos-NPU, edge-TPU, Qualcomm-SNPE, ...)
+  - NNFW-Runtime/nnfw (stable)
+  - Edge-TPU (stable)
+  - openVINO (stable)
+  - ARMNN (stable)
+  - WIP: Verisilicon-Vivante, SNAP (Exynos-NPU & Qualcomm-SNPE), ...
   - [Guide on writing a filter subplugin](writing-subplugin-tensor-filter.md)
   - [Codegen and code template for tensor\_filter subplugin](https://github.com/nnsuite/nnstreamer-example/tree/master/templates)
 - [tensor\_sink](../gst/nnstreamer/tensor_sink) (stable)
@@ -69,6 +74,7 @@ In this page, we focus on the status of each elements. For requirements and desi
     - Image segmentation (video/x-raw) (stable)
     - Body pose (video/x-raw) (stable)
     - Users can add plugins in run-time.
+  - Planned: flatbuffers, protobuf
 - [tensor\_mux](../gst/nnstreamer/tensor_mux) (stable)
 - [tensor\_demux](../gst/nnstreamer/tensor_demux) (stable)
 - [tensor\_source](../gst/nnstreamer/tensor_source) (stable for IIO. More sources coming soon)
@@ -79,8 +85,6 @@ In this page, we focus on the status of each elements. For requirements and desi
 - [tensor\_src\_tizensensor](../ext/nnstreamer/tensor_source) (stable)
 - [tensor\_ros\_sink](https://github.com/nnsuite/nnstreamer-ros) (stable for ROS1)
 - [tensor\_ros\_src](https://github.com/nnsuite/nnstreamer-ros) (stable for ROS1)
-- [tensor\_flatbuffers\_src](../gst/) (planned)
-- [tensor\_flatbuffers\_sink](../gst/) (planned)
 - tensor\_save and tensor\_load canceled.
 
 
@@ -100,6 +104,7 @@ Note that test elements in /tests/ are not elements for applications. They exist
   - [Android sample app](https://github.com/nnsuite/nnstreamer-example/tree/master/android/example_app/api-sample) uses JAVA APIs to implement Android-NNStreamer apps.
   - [Available at JCenter](https://bintray.com/beta/#/nnsuite/nnstreamer?tab=packages)
   - Note that the Android Sample Applications published via Google Play Store, [Source Code](https://github.com/nnsuite/nnstreamer-example/tree/master/android/example_app), are developed before NNStreamer Java API. They use GStreamer functions.
+- Web API (HTML5) Planned (Tizen 7.0?)
 
 # Other Components
 - CI ([@AWS](http://nnsuite.mooo.com/nnstreamer/ci/taos)) (stable): Up and Running.

diff --git a/Documentation/contributing.md b/Documentation/contributing.md
index 6d883fd..99517bc 100644 (file)
--- a/Documentation/contributing.md
+++ b/Documentation/contributing.md
@@ -6,6 +6,8 @@ Consistent code conventions are important for several reasons:
 * To make it easy to debug the code, with both a system call tracer and GNU debuggers. It should be easy to set breakpoints, view locals, and display and view data structures.
 * To attempt to improve code quality through consistency, and requiring patterns that are less likely to result in bugs either initially, or after code modification.
 
+For more information, please refer to [coding-convention.md](coding-convention.md).
+
 ## Code Reviews and PRs
 
 Please review incoming PRs; regardless whether you are a maintainer, a designated reviewer, or just a passer-by.
@@ -19,9 +21,23 @@ The submitter has the first responsibility of keeping the created PR clean and n
 * Each feature should come with a rich set of test cases that can be executed as unit tests during build. If the feature is more invasive or richer, you need more and richer test cases. Refer to other test cases in /tests directory, which use either GTest or SSAT.
 * Try to stick with C89. Try to avoid introducing additional dependencies of libraries. If you are going to use C++ or additional libraries, your codes may be located at /ext/* so that they can be "optional" features.
 * If your functions or structs/classes are going to be accessed by other modules or NNStreamer users, provide full descriptions of all entries with Doxygen.
-* Passing all the tests of TAOS-CI is a neccesary condition, but not a satisfying condition.
+* Passing all the tests of TAOS-CI is a necessary condition, but not a satisfying condition.
+
+### Merge Criteria
+
+A PR is required to meet the following criteria.
+* It has passed all the tests defined for TAOS-CI.
+    - This includes unit tests and integration tests in various platforms and different static analysis tools.
+    - Note that one of the tests includes the "Signed-off-by" check, which means that the author has agreed with [Code of Conduct](../CODE_OF_CONDUCT.md). You may need to refer to later section.
+* At least TWO official reviewers have approved the PR.
+    - This does not guarantee accepts. This is a necessary condition, not sufficient.
+    - If the PR touches sensitive codes or may affect wide ranges of components, reviewers will wait for other reviewers to back them up.
+    - If the PR is messy, you will need to wait indefinitely to get reviews.
+        - Apply general rules of git commits and common senses.
+        - Do not write a lengthy commit. Apply a single commit per PR if you are new to the community. Have a single topic per commit. Provide enough background information and references. And so on.
+* There is no rejections from any official reviewers.
+* There is no pending negative feedbacks (unresolved issues) from reviewers.
 
-### Any commits are required to be reviewed and approved before merged.
 
 ## Signing off commits