1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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
|
