summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--configure.ac14
-rw-r--r--tests/experimental/.gitignore7
-rw-r--r--xlators/Makefile.am6
-rw-r--r--xlators/experimental/Makefile.am3
-rw-r--r--xlators/experimental/README.md107
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