summaryrefslogtreecommitdiffstats
path: root/xlators
diff options
context:
space:
mode:
authorShyam <srangana@redhat.com>2015-10-08 13:59:44 -0400
committerJeff Darcy <jdarcy@redhat.com>2015-11-18 04:23:02 -0800
commit73200eaa8559c770a0ccc6e819cf791564592335 (patch)
tree4b05e7f22c6dc7dbb72b79e3b57278e05cd97f1c /xlators
parent23440a73bc348bbc3bb43ec397f0639ee45865fc (diff)
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>
Diffstat (limited to 'xlators')
-rw-r--r--xlators/Makefile.am6
-rw-r--r--xlators/experimental/Makefile.am3
-rw-r--r--xlators/experimental/README.md107
3 files changed, 115 insertions, 1 deletions
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