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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
Simplified development workflow for GlusterFS
=============================================
This page gives a simplified model of the development workflow used by
the GlusterFS project. This will give the steps required to get a patch
accepted into the GlusterFS source.
Visit [Development Work Flow](./Development Workflow.md) a more
detailed description of the workflow.
Initial preperation
-------------------
The GlusterFS development workflow revolves around
[Git](http://git.gluster.org/?p=glusterfs.git;a=summary),
[Gerrit](http://review.gluster.org) and
[Jenkins](http://build.gluster.org).
Using these tools requires some initial preparation.
### Dev system setup
You should install and setup Git on your development system. Use your
distribution specific package manger to install git. After installation
configure git. At the minimum, set a git user email. To set the email
do,
$ git config --global user.name "Name"
$ git config --global user.email <email address>
You should also generate an ssh key pair if you haven't already done it.
To generate a key pair do,
$ ssh-keygen
and follow the instructions.
Next, install the build requirements for GlusterFS. Refer
[Building GlusterFS - Build Requirements](./Building GlusterFS.md#Build Requirements)
for the actual requirements.
### Gerrit setup
To contribute to GlusterFS, you should first register on
[gerrit](http://review.gluster.org).
After registration, you will need to select a username, set a preferred
email and upload the ssh public key in gerrit. You can do this from the
gerrit settings page. Make sure that you set the preferred email to the
email you configured for git.
### Get the source
Git clone the GlusterFS source using
<ssh://><username>@review.gluster.org/glusterfs.git
(replace <username> with your gerrit username).
$ git clone (ssh://)<username> @review.gluster.org/glusterfs.git
This will clone the GlusterFS source into a subdirectory named glusterfs
with the master branch checked out.
It is essential that you use this link to clone, or else you will not be
able to submit patches to gerrit for review.
Actual development
------------------
The commands in this section are to be run inside the glusterfs source
directory.
### Create a development branch
It is recommended to use separate local development branches for each
change you want to contribute to GlusterFS. To create a development
branch, first checkout the upstream branch you want to work on and
update it. More details on the upstream branching model for GlusterFS
can be found at
[Development Work Flow - Branching\_policy](./Development Workflow.md#branching-policy).
For example if you want to develop on the master branch,
$ git checkout master
$ git pull
Now, create a new branch from master and switch to the new branch. It is
recommended to have descriptive branch names. Do,
$ git branch <descriptive-branch-name>
$ git checkout <descriptive-branch-name>
or,
$ git checkout -b <descriptive-branch-name>
to do both in one command.
### Hack
Once you've switched to the development branch, you can perform the
actual code changes. [Build](./Building GlusterFS) and test to
see if your changes work.
#### Tests
Unless your changes are very minor and trivial, you should also add a
test for your change. Tests are used to ensure that the changes you did
are not broken inadvertently. More details on tests can be found at
[Development Workflow - Test cases](./Development Workflow.md#test-cases)
and
[Development Workflow - Regression tests and test cases](./Development Workflow.md#regression-tests-and-test-cases)
### Regression test
Once your change is working, run the regression test suite to make sure
you haven't broken anything. The regression test suite requires a
working GlusterFS installation and needs to be run as root. To run the
regression test suite, do
# make install
# ./run-tests.sh
### Commit your changes
If you haven't broken anything, you can now commit your changes. First
identify the files that you modified/added/deleted using git-status and
stage these files.
$ git status
$ git add <list of modified files>
Now, commit these changes using
$ git commit -s
Provide a meaningful commit message. The commit message policy is
described at
[Development Work Flow - Commit policy](./Development Workflow.md#commit-policy).
It is essential that you commit with the '-s' option, which will
sign-off the commit with your configured email, as gerrit is configured
to reject patches which are not signed-off.
### Submit for review
To submit your change for review, run the rfc.sh script,
$ ./rfc.sh
The script will ask you to enter a bugzilla bug id. Every change
submitted to GlusterFS needs a bugzilla entry to be accepted. If you do
not already have a bug id, file a new bug at [Red Hat
Bugzilla](https://bugzilla.redhat.com/enter_bug.cgi?product=GlusterFS).
If the patch is submitted for review, the rfc.sh script will return the
gerrit url for the review request.
More details on the rfc.sh script are available at
[Development Work Flow - rfc.sh](./Development Workflow.md#rfc.sh).
Review process
--------------
Your change will now be reviewed by the GlusterFS maintainers and
component owners on [gerrit](http://review.gluster.org). You can follow
and take part in the review process on the change at the review url. The
review process involves several steps.
To know component owners , you can check the "MAINTAINERS" file in root
of glusterfs code directory
### Automated verification
Every change submitted to gerrit triggers an initial automated
verification on [jenkins](http://build.gluster.org). The automated
verification ensures that your change doesn't break the build and has an
associated bug-id.
More details can be found at
[Development Work Flow - Auto verification](./Development Workflow.md#auto-verification).
### Formal review
Once the auto verification is successful, the component owners will
perform a formal review. If they are okay with your change, they will
give a positive review. If not they will give a negative review and add
comments on the reasons.
More information regarding the review qualifiers and disqualifiers is
available at
[Development Work Flow - Submission Qualifiers](./Development Workflow.md#submission-qualifiers)
and
[Development Work Flow - Submission Disqualifiers](./Development Workflow.md#submission-disqualifiers).
If your change gets a negative review, you will need to address the
comments and resubmit your change.
#### Resubmission
Switch to your development branch and make new changes to address the
review comments. Build and test to see if the new changes are working.
Stage your changes and commit your new changes using,
$ git commit --amend
'--amend' is required to ensure that you update your original commit and
not create a new commit.
Now you can resubmit the updated commit for review using the rfc.sh
script.
The formal review process could take a long time. To increase chances
for a speedy review, you can add the component owners as reviewers on
the gerrit review page. This will ensure they notice the change. The
list of component owners can be found in the MAINTAINERS file present in
the GlusterFS source
### Verification
After a component owner has given a positive review, a maintainer will
run the regression test suite on your change to verify that your change
works and hasn't broken anything. This verification is done with the
help of jenkins.
If the verification fails, you will need to make necessary changes and
resubmit an updated commit for review.
### Acceptance
After successful verification, a maintainer will merge/cherry-pick (as
necessary) your change into the upstream GlusterFS source. Your change
will now be available in the upstream git repo for everyone to use.
|
