# xlator classification and expectations

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

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

## Classifications
1. Experimental (E)
2. TechPreview (TP)
3. Maintained/Supported (M)
4. Sunset (S)
5. Deprecated (D)

### Experimental (E)

Developed in the experimental branch, for exploring new features. These are
NEVER released, and MAYBE packaged to help with getting feedback from
interested users.

#### Quality expectations
- Compiles
- Does not break nightly experimental regressions

### TechPreview (TP)

Features in master or release branches that are not complete for general
purpose consumption, but are mature enough to invite feedback and host user
data.

These features will receive better attention from maintainers/authors that are
working on maturing the same, than ones in Experimental/Sunset/Deprecated
states.

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

#### Quality expectations
- Same as Maintained, sans
- Performance, Scale, other(?)

### Maintained (M)

These features are part of the core Gluster functionality and are maintained
actively. These are part of master and release branches and get high priority
attention from 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

### Sunset (S)

Features on master or release branches that would be deprecated 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 deprecated

### Deprecated (D)

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

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

#### Quality expectations
- None

## Implementation details

### GD2

While adding a translator in a graph (any graph), if it has flag of 'Experimental', 'Sunset' or 'Deprecated', the 'volume create' would fail.
- This behavior would be over-ridden with '--force' like flag, but 'Deprecated' would not be allowed to be in the graph.
- This makes GD2 fail tests immediately once any xlator which are in use are marked bad in glusterfs, so gd2 volgen code can maintain sanctity.
- While shipping products based on glusterfs, companies can have the policy, or add separate flags for supporting 'TechPreview' or not. Upstream will allow techpreview to be added without failure.

### glusterfs enums

Because of above GD2 points, by default, the value of 0 for supportability means the feature is techpreview, so upsteam translators, unless not addressed, will continue to work (hence provides backward compatibility).
- TLC can take decision on translators which are not currently maintained (or not being present in MAINTAINERS file).
- It needs a code change, one of the members would own it up.

### Testing

There would be regression testing overhaul required.

* Only supported and maintained translators and features would be tested in per patch regression.
- `run-tests.sh -d tests/` would make run tests only from 'tests/' directory which would have only supported features.

* All tech-preview features would be run once a day in 'nightly-burn-in' tests.
- `run-tests.sh -d tests/ && run-tests.sh -d tests-nightly/`

* If a feature is supported, but is an option, which is not enabled by default, then developers can ask for specific nightly tests for that particular feature.
- like 'brick-mux', 'ctime-consistency' etc etc..

### GCS

It gets interesting with this coming into the mix. Mainly because Options required by GCS may not be default enabled in upstream glusterfs (like brick-mux), how should 'per-patch' tests capture this.
- I some time see the issue, as for brick-mux test, if its only required for GCS, should we run all regression? like bitrot, which is not required ?
- Which means we need a nightly tests for GCS focused setup, and we need to start early.
- This may be the easy way to start gd2 integration into regression, as gd2 regression needn't cover everything to start with.
- Helps to deliver GCS faster, for both upstream, and downstream.

## Current xlators and porposed classification

- cluster/afr - M
- cluster/ec - M
- cluster/dht - M
- cluster/stripe - S
- debug/delay-gen - E
- debug/error-gen - E
- debug/io-stats - M
- debug/sink - M
- debug/trace - TP
- encryption/crypt - E
- encryption/rot-13 - D
- experimental/fdl - E
- experimental/jbr - E
- experimental/posix2 - E
- experimental/rio - E
- features/arbiter - M
- features/barrier - M
- features/change-log - M
- features/ctr - D
- features/cloudsync - E
- features/compress - E
- features/gfid-access - M
- features/glupy - E
- features/index - M
- features/leases - E
- features/locks - M
- features/marker - TP
- features/namespace - E
- features/quisce - E
- features/quota - TP
- features/read-only - TP
- features/sdfs - E
- features/selinux - TP
- features/shard - M
- features/snapview-client - TP
- features/sapview-server - TP
- features/thin-arbiter - E
- features/trash - TP
- features/upcall - M
- features/utime - E
- mgmt/glusterd - S
- mgmt/gd2 - TP
- mount/fuse - M
- nfs/server - S
- performance/decompounder - TP
- performance/io-cache - S
- performance/io-threads - M
- performance/md-cache - S
- performance/nl-cache - TP
- performance/open-behind - S
- performance/quick-read - S
- performance/read-ahead - S
- performance/readdir-ahead - S
- performance/symlink-cache - D
- performance/write-behind - M
- protocol/auth-addr ??
- protocol/auth-login ??
- protocol/client - M
- protocol/server - M
- storage/bd - D
- storage/posix - M
- system/posix-acl - M
- events - TP
- geo-replication - M
- libglusterfs (needs details)
- rpc - S