core: Add experimental xlator directory

Added an experimental xlator directory under ./xlators/

The intent of this directory is presented in the README.md
that accompanies this commit.

This directory can be disabled from being compiled using,
  - configure --disable-experimental

Change-Id: I047f380c91a082d111432f8bbdbd4d7bdcbaa809
Signed-off-by: Shyam <srangana@redhat.com>
Reviewed-on: http://review.gluster.org/12321
Tested-by: NetBSD Build System <jenkins@build.gluster.org>
Reviewed-by: Kaleb KEITHLEY <kkeithle@redhat.com>
Reviewed-by: Avra Sengupta <asengupt@redhat.com>
Reviewed-by: Jeff Darcy <jdarcy@redhat.com>

5 files changed, 136 insertions, 1 deletions

diff --git a/configure.ac b/configure.ac
index f39a4cfff89..a345b88078b 100644
--- a/configure.ac
+++ b/configure.ac
@@ -186,6 +186,7 @@ AC_CONFIG_FILES([Makefile
                 xlators/mgmt/Makefile
                 xlators/mgmt/glusterd/Makefile
                 xlators/mgmt/glusterd/src/Makefile
+                xlators/experimental/Makefile
                 cli/Makefile
                 cli/src/Makefile
                 doc/Makefile
@@ -1259,6 +1260,18 @@ AC_SUBST(UNITTEST_LDFLAGS)
 AC_SUBST(CFLAGS)
 # end enable debug section
 
+# experimental section
+AC_ARG_ENABLE([experimental],
+              AC_HELP_STRING([--disable-experimental],
+                             [Disable building experimental xlators]))
+
+BUILD_EXPERIMENTAL="yes"
+if test "x$enable_experimental" == "xno"; then
+  BUILD_EXPERIMENTAL="no"
+fi
+AM_CONDITIONAL([ENABLE_EXPERIMENTAL], [test x$BUILD_EXPERIMENTAL = xyes])
+#end experimental section
+
 dnl libglusterfs.so uses math functions
 GF_LDADD="${GF_LDADD} ${MATH_LIB}"
 
@@ -1354,4 +1367,5 @@ echo "Unit Tests           : $BUILD_UNITTEST"
 echo "POSIX ACLs           : $BUILD_POSIX_ACLS"
 echo "Data Classification  : $BUILD_GFDB"
 echo "firewalld-config     : $BUILD_FIREWALLD"
+echo "Experimental xlators : $BUILD_EXPERIMENTAL"
 echo
diff --git a/tests/experimental/.gitignore b/tests/experimental/.gitignore
new file mode 100644
index 00000000000..803908720af
--- /dev/null
+++ b/tests/experimental/.gitignore
@@ -0,0 +1,7 @@
+# Initial commit, git needs a file to add a directory
+# First tests to appear here, should remove this file
+# Directives:
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore
diff --git a/xlators/Makefile.am b/xlators/Makefile.am
index 2b66201035d..ea1be844ef4 100644
--- a/xlators/Makefile.am
+++ b/xlators/Makefile.am
@@ -1,5 +1,9 @@
+if ENABLE_EXPERIMENTAL
+  EXPERIMENTAL = experimental
+endif
+
 SUBDIRS = cluster storage protocol performance debug features encryption mount nfs mgmt system \
-          playground meta
+          playground meta $(EXPERIMENTAL)
 
 EXTRA_DIST = xlator.sym
 
diff --git a/xlators/experimental/Makefile.am b/xlators/experimental/Makefile.am
new file mode 100644
index 00000000000..e182a87eb77
--- /dev/null
+++ b/xlators/experimental/Makefile.am
@@ -0,0 +1,3 @@
+SUBDIRS =
+
+CLEANFILES =
diff --git a/xlators/experimental/README.md b/xlators/experimental/README.md
new file mode 100644
index 00000000000..b00f24e114b
--- /dev/null
+++ b/xlators/experimental/README.md
@@ -0,0 +1,107 @@
+# Purpose of this directory
+
+This directory is created to host experimental gluster translators. A new
+translator that is *experimental* in nature, would need to create its own
+subdirectory under this directory, to host/publish its work.
+
+Example:
+  The first commit should include the following changes
+    1. xlators/experimental/Makefile.am
+      NOTE: Add foobar to the list of SUBDIRS here
+    2. xlators/experimental/foobar
+    3. xlators/experimental/foobar/Makefle.am
+      NOTE: Can be empty initially in the first commit
+    4. configure.ac
+      NOTE: Include your experimental Makefile under AC_CONFIG_FILES
+    5. xlators/experimental/foobar/README.md
+      NOTE: The readme should cover details as required for the translator to be
+      accepted as experimental, primarily including a link to the specification
+      under the gluster-specs repository [1]. Later the readme should suffice
+      as an entry point for developers and users alike, who wish to experiment
+      with the xlator under development
+    6. xlators/experimental/foobar/TODO.md
+      NOTE: This is a list of TODO's identified during the development process
+      that needs addressing over time. These include exceptions granted during
+      the review process, for things not addressed when commits are merged into
+      the repository
+
+# Why is it provided
+
+Quite often translator development that happens out of tree, does not get
+enough eyeballs early in its development phase, has not undergone CI
+(regression/continuous integration testing), and at times is not well integrated
+with the rest of gluster stack.
+
+Also, when such out of tree translators are submitted for acceptance, it is a
+bulk commit that makes review difficult and inefficient. Such submissions also
+have to be merged forward, and depending on the time spent in developing the
+translator the master branch could have moved far ahead, making this a painful
+activity.
+
+Experimental is born out of such needs, to provide xlator developers,
+  - Early access to CI
+  - Ability to adapt to ongoing changes in other parts of gluster
+  - More eye balls on the code and design aspects of the translator
+  - TBD: What else?
+
+and for maintainers,
+  - Ability to look at smaller change sets in the review process
+  - Ability to verify/check implementation against the specification provided
+
+# General rules
+
+1. If a new translator is added under here it should, at the very least, pass
+compilation.
+
+2. All translators under the experimental directory are shipped as a part of
+gluster-experimental RPMs.
+TBD: Spec file and other artifacts for the gluster-experimental RPM needs to be
+fleshed out.
+
+3. Experimental translators can leverage the CI framework as needed. Tests need
+to be hosted under xlators/experimental/tests initially, and later moved to the
+appropriate tests/ directory as the xlator matures. It is encouraged to provide
+tests for each commit or series of commits, so that code and tests can be
+inspected together.
+
+4. If any experimental translator breaks CI, it is quarantined till demonstrable
+proof towards the contrary is provided. This is applicable as tests are moved
+out of experimental tests directory to the CI framework directory, as otherwise
+experimental tests are not a part of regular CI regression runs.
+
+5. An experimental translator need not function at all, as a result commits can
+be merged pretty much at will as long as other rules as stated are not violated.
+
+6. Experimental submissions will be assigned a existing maintainer, to aid
+merging commits and ensure aspects of gluster code submissions are respected.
+When an experimental xlator is proposed and the first commit posted
+a mail to gluster-devel@gluster.org requesting attention, will assign the
+maintainer buddy for the submission.
+NOTE: As we scale, this may change.
+
+6. More?
+
+# Getting out of the experimental jail
+
+So you now think your xlator is ready to leave experimental and become part of
+mainline!
+- TBD: guidelines pending.
+
+# FAQs
+
+1. How do I submit/commit experimental framework changes outside of my
+experimental xlator?
+  - Provide such framework changes as a separate commit
+  - Conditionally ensure these are built or activated only when the experimental
+  feature is activated, so as to prevent normal gluster workflow to function as
+  before
+  - TBD: guidelines and/or examples pending.
+
+2. Ask your question either on gluster-devel@gluster.org or as a change request
+to this file in gluster gerrit [2] for an answer that will be assimilated into
+this readme.
+
+# Links
+[1] http://review.gluster.org/#/q/project:glusterfs-specs
+
+[2] http://review.gluster.org/#/q/project:glusterfs