diff options
| -rw-r--r-- | configure.ac | 14 | ||||
| -rw-r--r-- | tests/experimental/.gitignore | 7 | ||||
| -rw-r--r-- | xlators/Makefile.am | 6 | ||||
| -rw-r--r-- | xlators/experimental/Makefile.am | 3 | ||||
| -rw-r--r-- | xlators/experimental/README.md | 107 |
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 |