You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apex.apache.org by th...@apache.org on 2016/08/15 17:05:46 UTC
[1/2] apex-site git commit: Added malhar contribution guidelines
Repository: apex-site
Updated Branches:
refs/heads/master 45f9cd803 -> ad8ec758b
Added malhar contribution guidelines
Project: http://git-wip-us.apache.org/repos/asf/apex-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/apex-site/commit/7a682a59
Tree: http://git-wip-us.apache.org/repos/asf/apex-site/tree/7a682a59
Diff: http://git-wip-us.apache.org/repos/asf/apex-site/diff/7a682a59
Branch: refs/heads/master
Commit: 7a682a5913aec650610a3ea97eec279ced97e985
Parents: c1498b1
Author: Pramod Immaneni <pr...@datatorrent.com>
Authored: Mon Jul 25 19:41:06 2016 -0700
Committer: Pramod Immaneni <pr...@datatorrent.com>
Committed: Sun Aug 14 16:14:29 2016 -0700
----------------------------------------------------------------------
src/md/community.md | 4 ++++
src/md/malhar-contributing.md | 35 +++++++++++++++++++++++++++++++++
src/pages/malhar-contributing.html | 9 +++++++++
3 files changed, 48 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/apex-site/blob/7a682a59/src/md/community.md
----------------------------------------------------------------------
diff --git a/src/md/community.md b/src/md/community.md
index 21003cd..00dc53b 100644
--- a/src/md/community.md
+++ b/src/md/community.md
@@ -33,6 +33,10 @@ The Apex Project is made up of two repositories:
- [Apex Core](https://github.com/apache/apex-core) - The core of the Apex platform.
- [Apex Malhar](https://github.com/apache/apex-malhar) - Community-driven set of open-source "operators" and utilities for use in your Apex applications.
+## Malhar contribution
+
+If you are new to the project and thinking about contributing, Apex Malhar is a good place to start. To make contributions to this module, please [follow these guidelines](/malhar-contributing.html).
+
## Release Process
To learn more about the release process for Apex, [check out the release guidelines](/release.html).
http://git-wip-us.apache.org/repos/asf/apex-site/blob/7a682a59/src/md/malhar-contributing.md
----------------------------------------------------------------------
diff --git a/src/md/malhar-contributing.md b/src/md/malhar-contributing.md
new file mode 100644
index 0000000..218f167
--- /dev/null
+++ b/src/md/malhar-contributing.md
@@ -0,0 +1,35 @@
+# Malhar Contribution Guidelines
+
+Malhar library predominantly contains different kinds of operators like connectors to messaging systems, databases, key-value and document stores, block i/o operators like various file system operators, analytic and algorithmic operators and other miscellaneous operators. It also provides other components to build applications such as partitioners, stats listeners, stream codecs and state management. This document outlines the general steps for making contributions to Malhar. Even though the processes described in the rest of the document refer to Operators in particular, they also generally apply to other application components mentioned above.
+
+## Operators
+
+* Follow the unix philosophy, design your operator to do one thing and do it well. If the operator is doing multiple things, you may not be taking advantage of platform parallelism aspects like pipelining to the fullest extent (akin to unix pipes).
+
+* Search Malhar project to see if there is an operator with similar functionality before embarking on writing a new one
+ * If an operator that is supposed to solve the same problem is already present but isn\u2019t complete or does not have the required functionality, consider making improvements to it. There should be a strong reason to not do this and create a new one.
+ * If there is an overlap in functionality with an existing operator or an operator that is designed to be extended, do not rewrite that functionality. Create the new operator in such a way that it reuses code already present and implements the new functionality on top of it. This might require refactoring of existing operator(s).
+* If the functionality requires connecting two or more operators together, do that in the application. If this pattern would be useful to others and can be reused in other applications consider making it a module.
+
+## Preparation for making changes
+
+If after performing the above analysis, there is a need to write a new operator or update an existing one, follow these steps
+
+* Make the case on [dev mailing list](/community.html#mailing-lists) as to why the changes are needed and propose any design that you are thinking of.
+* If writing a new operator, mention any existing operators you considered, that have related or partially matching functionality to the desired functionality and why they cannot be improved to meet the requirements.
+* Also mention which folder under Malhar the operator would go into. If scalability and recovery features such as partitioning, idempotency etc., are not going to be implemented then the operator should go into **contrib**. For more explanation, see implementing an operator section below.
+* Respond to comments and suggestions and make appropriate modifications to design that are consistent with the evolving consensus.
+* Summarize the final list of changes in an email.
+* Create a [JIRA](https://issues.apache.org/jira/browse/APEXMALHAR) to track the work.
+* Work on the changes.
+
+## Implementing an operator
+
+* Look at the [Operator Development Guide](/docs/apex/operator_development) and the [Best Practices Guide](/docs/malhar/development_best_practices) on how to implement an operator and what the dos and don'ts are.
+* Refer to existing operator implementations when in doubt or unsure about how to implement some functionality. You can also email the [dev mailing list](/community.html#mailing-lists) with any questions.
+* Write unit tests for operators
+ * Refer to unit tests for existing operators.
+ * If possible write a sample application testing the operator.
+ * Try to keep the tests self contained i.e., avoid the user having to perform additional setup or setup other services before running the tests. This can be done by starting mock versions of the required services from within the test and shutting them down when the test finishes.
+* Follow the code style guidelines of the Apache Apex project described [here](http://apex.apache.org/contributing.html#code-style).
+* If only the core operator business logic for the operator is implemented and advanced platform functionality for scalability and recovery, such as partitioning, idempotence etc., described in the above reference guides are not implemented, make the code submission pull request to the **contrib** folder in Malhar, otherwise make it to an appropriate top-level module or a new one if one is not present.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/apex-site/blob/7a682a59/src/pages/malhar-contributing.html
----------------------------------------------------------------------
diff --git a/src/pages/malhar-contributing.html b/src/pages/malhar-contributing.html
new file mode 100644
index 0000000..46e4f58
--- /dev/null
+++ b/src/pages/malhar-contributing.html
@@ -0,0 +1,9 @@
+{{> header}}
+
+<div class="container">
+
+ {{> malhar-contributing}}
+
+</div>
+
+{{> footer}}
[2/2] apex-site git commit: Merge branch 'malhar-contribution' of
https://github.com/PramodSSImmaneni/apex-site
Posted by th...@apache.org.
Merge branch 'malhar-contribution' of https://github.com/PramodSSImmaneni/apex-site
Project: http://git-wip-us.apache.org/repos/asf/apex-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/apex-site/commit/ad8ec758
Tree: http://git-wip-us.apache.org/repos/asf/apex-site/tree/ad8ec758
Diff: http://git-wip-us.apache.org/repos/asf/apex-site/diff/ad8ec758
Branch: refs/heads/master
Commit: ad8ec758bc5e9a75eb1536c75d2d3d512c1ee440
Parents: 45f9cd8 7a682a5
Author: Thomas Weise <th...@datatorrent.com>
Authored: Mon Aug 15 10:01:08 2016 -0700
Committer: Thomas Weise <th...@datatorrent.com>
Committed: Mon Aug 15 10:01:08 2016 -0700
----------------------------------------------------------------------
src/md/community.md | 4 ++++
src/md/malhar-contributing.md | 35 +++++++++++++++++++++++++++++++++
src/pages/malhar-contributing.html | 9 +++++++++
3 files changed, 48 insertions(+)
----------------------------------------------------------------------