Github user tweise commented on a diff in the pull request:
https://github.com/apache/apex-site/pull/44#discussion_r72503860
--- Diff: src/md/malhar-contributing.md ---
@@ -0,0 +1,41 @@
+# 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ât 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.
+
+## Updating an existing Operator
+
+If after performing the above analysis, there is a need to update an
existing operator, follow these steps
+
+* Make the case on dev email list as to why an update is needed and
propose any design that you are thinking of.
+* Specify which module you are going to submit the operator or contrib if
the operator is not going to have any platform functionality. 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 to track the work.
+* Work on the changes.
+
+## Writing a new Operator
+
+If a new operator needs to be written
+
+* Similar steps as the previous case
+* Also mention in your email, any existing operators you considered and
why they cannot be used or improved to meet the requirement.
+
+## Implementing an operator
+
+* Look at the Operator developer guide and the [Operator best practices
guide](/docs/malhar/development_best_practices) on how to implement an operator
and the dos and don'ts.
+* Refer to existing operator implementations when in doubt or unsure about
how to implement some functionality. You can also email the dev list 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 Malhar project.
--- End diff --
http://apex.apache.org/contributing.html#code-style
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
