summaryrefslogtreecommitdiffstats
path: root/doc/markdown/dev_guide.md
blob: 52dcf011e42119b144e80c6a70ecddb5c1f9ea13 (plain)
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
# Developer Guide

## Contributing to the project

## Development Environment Setup
The workflow for Gluster-Swift is largely based upon the 
[OpenStack Gerrit Workflow][].

### Account Setup
Gluster for Swift uses [Gerrit][] as a code review system.  Create an
account in [review.gluster.org][], then generate and upload
an [SSH key][] to the website.  This will allow you to upload
changes to Gerrit.  Follow the the information given
at [GitHub Generating SSH Keys][] if you need help creating your key.

### Download the source
The source for Gluster for Swift is available in Github.  To download
type:

~~~
git clone https://github.com/gluster/gluster-swift.git
cd gluster-swift
~~~

### Git Review
The tool `git review` is a simple tool to automate interaction with Gerrit.
We recommend using this tool to upload, modify, and query changes in Gerrit.
The tool can be installed by running the following command:

~~~
sudo pip install git-review
~~~

Note that while many distros offer a version of `git review`, they don't
necessarily keep it up to date. Pip gives one the latest which
often avoids problems with various Gerrit servers.

We now need to setup `git review` to communicate with review.gluster.org.
First, let's determine our `git review` setup by typing:

~~~
git review -s
~~~

If there is no output, then everything is setup correctly.  If the output
contains the string *We don't know where your gerrit is*, then we need
a setup a remote repo with the name `gerrit`.  We can inspect the current
remote repo's by typing the following command.

~~~
git remote -v
~~~

To add the Gerrit remote repo, type the following:

~~~
git remote add gerrit ssh://<username>@review.gluster.org/gluster-swift
git remote -v
~~~

Now we can confirm that `git review` has been setup by typing the
following and noticing no output is returned:

~~~
git review -s
~~~

### Tox and Nose
Like OpenStack Swift, Gluster for Swift uses `tox` python virtual 
environment for its unit tests.  To install `tox` type:

~~~
pip install tox nose
~~~

## Workflow

### Create a topic branch
It is recommended to create a branch in git when working on a specific topic.
If you are currently on the *master* branch, you can type the following
to create a topic branch:

~~~
git checkout -b TOPIC-BRANCH
~~~

where *TOPIC-BRANCH* is either bug/bug-number (e.g. bug/123456) or
a meaningful name for the topic (e.g. feature_xyz)

### Quality Checking
#### PEP8
To test that the code adheres to the [PEP8][] specification, please
type:

~~~
tox -e pep8
~~~

#### Unit Tests
You can run the unit tests after making your changes.  To run the unit
test suite in `tox` type the following as a non-root user:

~~~
tox -e ENV
~~~

where *ENV* is either `py27` for systems with Python 2.7+, or `py26` for
systems with Python 2.6+.

#### Functional Tests
To run the functional tests the following requirements must be met.

1) "/etc/swift" must not exist. So that test would not interfere with
existing setup. Functional test would create "/etc/swift" and populate
it with necessary configuration files.
2) User need to have administrative access.
2) "/mnt/gluster-object" directory must be created.
3) Volumes named "test", "test2" should be created. (Gluster volume / XFS
volume)
4) Volumes should be mounted under "/mnt/gluster-object/test" and
"/mnt/gluster-object/test2" respectively.

####To run functional tests:
~~~
tools/functional_tests.sh
~~~

### Commiting changes
After making the changes needed, you can commit your changes by typing:

~~~
git commit -as
~~~

where the commit message should follow the following recommendations:

1. The first line should be a brief message and contain less than 50
characters.
2. Second line blank
3. A line, or multiple line description of the change where each line
contains less than 70 characters.
4. Blank line
5. If this is a bug fix, then it should have a line as follows:
`BUG 12345: <url to bug>`
6. Blank line.

For more information on commit messages, please visit the
[Git Commit Messages][] page in OpenStack.org.

### Uploading to Gerrit
Once you have the changes ready for review, you can submit it to Gerrit
simply by typing:

~~~
git review
~~~

After the change is reviewed, most likely you may have to make some
additional modifications to your change.  To continue the work for
a specific change, you can query Gerrit for the change number by
typing:

~~~
git review -l
~~~

Then download the change to make the new modifications by typing:

~~~
git review -d CHANGE_NUMBER
~~~

where CHANGE_NUMBER is the Gerrit change number.

If you need to create a new patch for a change and include your update(s)
to your last commit type:

~~~
git commit -as --amend
~~~

Now that you have finished updating your change, you need to re-upload
to Gerrit using the following command:

~~~
git review
~~~

## Creating Distribution Packages

### Tools Installation
TBD:  For now please follow the installation instructions
on the [GlusterFS Compiling RPMS][] page.

### Building RPMs for Fedora/RHEL/CentOS Systems
Building RPMs.  RPMs will be located in the *build* directory.

`$ bash makerpm.sh`

Building RPM with a specific release value, useful for automatic
Jenkin builds, or keeping track of different versions of the
RPM:

`$ PKG_RELEASE=123 bash makerpm.sh`


[OpenStack Gerrit Workflow]: https://wiki.openstack.org/wiki/Gerrit_Workflow
[Gerrit]: https://code.google.com/p/gerrit/
[review.gluster.org]: http://review.gluster.org
[SSH Key]: http://review.gluster.org/#/settings/ssh-keys
[GitHub Generating SSH Keys]: https://help.github.com/articles/generating-ssh-keys
[PEP8]: http://www.python.org/dev/peps/pep-0008
[Git Commit Messages]: https://wiki.openstack.org/wiki/GitCommitMessages
[GlusterFS Compiling RPMS]: https://forge.gluster.org/glusterfs-core/pages/CompilingRPMS