glusterfs/doc/developer-guide/xlator-classification.md

xlator categories and expectations

The purpose of the document is to define a category for various xlators and expectations around what each category means from a perspective of health and maintenance of a xlator.

The need to do this is to ensure certain categories are kept in good health, and helps the community and contributors focus their efforts around the same.

This document also provides implementation details for xlator developers to declare a category for any xlator.

Table of contents

1. Audience
2. Categories (and expectations of each category)
3. Implementation and usage details

Audience

This document is intended for the following community participants,

• New xlator contributors
• Existing xlator maintainers
• Packaging and gluster management stack maintainers

For a more user facing understanding it is recommended to read section (TBD) in the gluster documentation.

Categories

1. Experimental (E)
2. TechPreview (TP)
3. Maintained (M)
4. Deprecated (D)
5. Obsolete (O)

Experimental (E)

Developed in the experimental branch, for exploring new features. These xlators are NEVER packaged as a part of releases, interested users and contributors can build and work with these from sources. In the future, these maybe available as an package based on a weekly build of the same.

Quality expectations

• Compiles or passes smoke tests
• Does not break nightly experimental regressions
  • NOTE: If a nightly is broken, then all patches that were merged are reverted till the errant patch is found and subsequently fixed

TechPreview (TP)

Xlators in master or release branches that are not deemed fit to be in production deployments, but are feature complete to invite feedback and host user data.

These xlators will be worked upon with priority by maintainers/authors who are involved in making them more stable than xlators in the Experimental/Deprecated/ Obsolete categories.

There is no guarantee that these xlators will move to the Maintained state, and may just get Obsoleted based on feedback, or other project goals or technical alternatives.

Quality expectations

• Same as Maintained, minus
  • Performance, Scale, other(?)
  • TBD NOTE Need inputs, Intention is all quality goals as in Maintained, other than the list above (which for now has scale and performance)

Maintained (M)

These xltors are part of the core Gluster functionality and are maintained actively. These are part of master and release branches and are higher in priority of maintainers and other interested contributors.

Quality expectations

NOTE: A short note on what each of these mean are added here, details to follow.

NOTE: Out of the gate all of the following are not mandated, consider the following a desirable state to reach as we progress on each

• Bug backlog: Actively address bug backlog
• Enhancement backlog: Actively maintain outstanding enhancement backlog (need not be acted on, but should be visible to all)
• Review backlog: Actively keep this below desired counts and states
• Static code health: Actively meet near-zero issues in this regard
  • Coverity, spellcheck and other checks
• Runtime code health: Actively meet defined coverage levels in this regard
  • Coverage, others?
  • Per-patch regressions
  • Glusto runs
  • Performance
  • Scalability
• Technical specifications: Implementation details should be documented and updated at regular cadence (even per patch that change assumptions in here)
• User documentation: User facing details should be maintained to current status in the documentation
• Debuggability: Steps, tools, procedures should be documented and maintained each release/patch as applicable
• Troubleshooting: Steps, tools, procedures should be documented and maintained each release/patch as applicable
  • Steps/guides for self service
  • Knowledge base for problems
• Other common criteria that will apply: Required metrics/desired states to be defined per criteria
  • Monitoring, usability, statedump, and other such xlator expectations

Deprecated (D)

Xlators on master or release branches that would be obsoleted and/or replaced with similar or other functionality in the next major release.

Quality expectations

• Retain status-quo when moved to this state, till it is moved to obsoleted
• Provide migration steps if feature provided by the xlator is replaced with other xlators

Obsolete (O)

Xlator/code still in tree, but not packaged or shipped or maintained in any form. This is noted as a category till the code is removed from the tree.

These xlators and their corresponding code and test health will not be executed.

Quality expectations

• None

Implementation and usage details

How to specify an xlators category

While defining 'xlator_api_t' structure for the corresponding xlator, add a flag like below:

diff --git a/xlators/performance/nl-cache/src/nl-cache.c b/xlators/performance/nl-cache/src/nl-cache.c
index 0f0e53bac2..8267d6897c 100644
--- a/xlators/performance/nl-cache/src/nl-cache.c
+++ b/xlators/performance/nl-cache/src/nl-cache.c
@@ -869,4 +869,5 @@ xlator_api_t xlator_api = {
         .cbks          = &nlc_cbks,
         .options       = nlc_options,
         .identifier    = "nl-cache",
+        .category      = GF_TECH_PREVIEW,
 };
diff --git a/xlators/performance/quick-read/src/quick-read.c b/xlators/performance/quick-read/src/quick-read.c
index 8d39720e7f..235de27c19 100644
--- a/xlators/performance/quick-read/src/quick-read.c
+++ b/xlators/performance/quick-read/src/quick-read.c
@@ -1702,4 +1702,5 @@ xlator_api_t xlator_api = {
         .cbks          = &qr_cbks,
         .options       = qr_options,
         .identifier    = "quick-read",
+        .category      = GF_MAINTAINED,
 };

Similarly, if a particular option is in different state other than the xlator state, one can add the same flag in options structure too.

diff --git a/xlators/cluster/afr/src/afr.c b/xlators/cluster/afr/src/afr.c
index 0e86e33d03..81996743d1 100644
--- a/xlators/cluster/afr/src/afr.c
+++ b/xlators/cluster/afr/src/afr.c
@@ -772,6 +772,7 @@ struct volume_options options[] = {
           .description = "Maximum latency for shd halo replication in msec."
         },
         { .key   = {"halo-enabled"},
+          .category = GF_TECH_PREVIEW,
           .type  = GF_OPTION_TYPE_BOOL,
           .default_value = "False",

User experience using the categories

Ability to use a category

This section details which category of xlators can be used when and specifics around when each category is enabled.

1. Maintained category xlators can be used by default, this implies, volumes created with these xlators enabled will throw no warnings, or need no user intervention to use the xlator.

2. Tech Preview category xlators needs cluster configuration changes to allow these xlatorss to be used in volumes, further, logs will contain a message stating TP xlators are in use. Without the cluster configured to allow TP xlators, volumes created or edited to use such xlators would result in errors.

• (TBD) Cluster configuration option
• (TBD) Warning message
• (TBD) Code mechanics on how this is achieved

3. Deprecated category xlators can be used by default, but will throw a warning in the logs that such are in use and will be deprecated in the future.

• (TBD) Warning message

4. Obsolete category xlators will not be packaged and hence cannot be used from release builds.

5. Experimental category xlators will not be packaged and hence cannot be used from release builds, if running experimental (weekly or other such) builds, these will throw a warning in the logs stating experimental xlators are in use.

• (TBD) Warning message

Ability to query xlator category

(TBD) Need to provide the ability to query xlator categories, or list xlators and their respective categories.

User facing changes

User facing changes that are expected due to this change include the following,

• Cluster wide option to enable TP xlators, or more generically a category level of xlators
• Errors in commands that fail due to invalid categories
• Warning messages in logs to denote certain categories of xlators are in use
• (TBD) Ability to query xlators and their respective categories