Project: Gluster (Runtime / Cloud Native Storage)
File: xlator-classification.md

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. Audience Categories (and expectations of each category) Implementation and usage details 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. Experimental (E) TechPreview (TP) Maintained (M) Deprecated (D) Obsolete (O) 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. 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 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. 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) 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. NOTE: A short note on what each of these mean are added here, details to

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 Xlators on master or release branches that would be obsoleted and/or replaced with similar or other functionality in the next major release. 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 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. None While defining 'xlatorapit' 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 @@ xlatorapit xlator_api = { .cbks = &nlc_cbks, .options = nlc_options, .identifier = "nl-cache", .category = GFTECHPREVIEW, }; 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 @@ xlatorapit 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 = GFTECHPREVIEW, .type = GFOPTIONTYPE_BOOL, .default_value = "False", ``` This section details which category of xlators can be used when and specifics around when each category is enabled. 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. 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 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 Obsolete category xlators will not be packaged and hence cannot be used from release builds. Experimental category xlators will not be packaged and hence cannot be used from release builds, if running experimental (weekly or other such)