Upgrade to 4.2.2
[usit-rt.git] / docs / hacking.pod
CommitLineData
84fb5b46
MKG
1=head1 Development of RT
2
3RT's source code is stored in a C<git> repository. If you are not
4familiar with git, see L</git quickstart>, below, for a short tutorial
5which will give you enough information to get started submitting patches
6to RT.
7
8The rest of this document details conventions and tips surrounding the
9organization of RT's version control, source code conventions, and how
10to submit patches.
11
12
13
14=head1 Organization of rt.git
15
16The RT source repository is available via git from GitHub; you can
17browse it at L<http://github.com/bestpractical/rt/> or obtain a local
18copy via:
19
20 git clone git://github.com/bestpractical/rt.git
21
22The bleeding-edge development happens in the C<master> branch. When a
23major release is anticipated, a "trunk" branch will be branched from
24this -- for example, C<4.0-trunk>. This will allow the trunk to
25stabilize while feature development continues on C<master>.
26Additionally, as a release is impending for a particular series, a
27release engineering branch will be created, named, for example
28C<4.0.0-releng>.
29
30New feature development should always be based off of the C<master>
31branch. Branches to fix bugs should be based off of whichever trunk the
32bug was first found in. If you found the bug in your RT 4.0.0 install,
33you'd branch from 4.0-trunk.
34
35Branches should be named based on the trunk they are branched
36from -- which is to say, the earliest branch they might be merged into.
37For example, a bugfix branched from C<4.0-trunk> might be named
38C<4.0/fail-taint-mode-early>. A feature branched from C<master> when
39there exists a C<4.0-trunk> but no C<4.2-trunk> might be named
40C<4.2/rename-LogToScreen>. For consistency, branches should use dashes,
403d7b0b
MKG
41not underscores, to separate words. Branches which are destined for
424.2, but which are branched from 4.0 (to provide for easy extraction as
43a 4.0 extension) should be named 4.2-on-4.0/branch-name.
84fb5b46
MKG
44
45Branches should be reviewed by another developer before being merged.
46Reviewers should make sure that the branch accomplishes what it claims
47to, and does not introduce any unwanted behavior in doing so. Commit
48messages explain the B<why> as much as the B<what> of each commit, and
49not include extranous changes.
50
51
52=head1 Code conventions
53
54The RT codebase is more than ten years old; as such, there are sections
55which do not (yet) conform to the guidelines below. Please attempt to
56follow the guidelines, even if the code surrounding your changes does
57not yet.
58
59RT also includes a F<.perltidyrc> in its top-level which encodes many of
60the conventions.
61
62=over
63
64=item Indentation
65
66Each level of indentation should be four spaces; tabs should never be
67used for indentation.
68
69=back
70
71=head1 Internationalization
72
73RT has been translated into several dozen languages. We use Launchpad
74( https://translations.launchpad.net/rt ) to crowdsource our
75translations into C<po> files. RT uses L<Locale::Maketext> to
76localize its user interface.
77
78Your first stop on this magical journey of internationalization
79is L<Locale::Maketext::TPJ13>, which explains the whys of
80L<Locale::Maketext>. RT uses most of the features developed in that
81article.
82
83Strings that are displayed to users should be passed through the
84C<loc("...")> function or the C<< <&|/l&>...</&> >> Mason template.
85C<loc> and C</l> both take parameters, which are used in place of
86string interpolation (much like C<sprintf>). It's acceptable to use
87HTML in C</l> calls, especially for bold and emphasis. However, you
88should limit the amount of HTML that translators must keep exactly
89correct, which means avoid including tags that wrap the entire
90translatable string, especially C<< <p> >>.
91
92 <p><&|/l, $button &>Do <em>not</em> click [_1]</&></p> # ok
93
94 <&|/l, $button &><p>Do <em>not</em> click [_1]</p></&> # not ok
95
96In a few places in RT we also pass HTML as parameters to C<loc()>
97so that translators do not have to reproduce it exactly, and we can
98also change it more freely. For example:
99
100 <&|/l,
101 '<a href="http://www.gnu.org/licenses/gpl-2.0.html">',
102 '</a>',
103 &>Distributed under [_1]version 2 of the GNU GPL[_2].</&>
104
105F<devel/tools/extract-message-catalog> looks for C<loc("...")> and
106C<< <&|/l&>...</&> >> in our source code to pick out translatable
107strings, clean them up, and put them into F<share/po> files. We use
108our C<.po> files not only to populate L<Locale::Maketext>'s lexicons,
109but also to sync new translatable strings and translations with
110Launchpad. This Launchpad sync is typically done early during the
111freeze of RC releases to give our volunteer translators time to
112translate all the new strings which, because of the RC freeze, won't
113continue changing.
114
115Because C<loc()> and C</l> are used to generate strings for human
116eyes, they generally must be used "close to the browser". These are
117directly in Mason templates, or in functions that return text that
118will be passed through Mason. However, in many places in RT we have
119hardcoded strings which need translations. For example, the C<$RIGHTS>
120hash in F<lib/RT/Queue.pm> maps rights' names (which must be
121translatable) to their descriptions (which also must be translatable).
122However, when we're declaring such structures, we do not want to
123translate them straight away. RT uses English internally, including
124in its web forms, so we do not want to localize rights' names except
125for display, otherwise things might break weirdly when you check
126if a user has the "Superusuario" right. Furthermore, when we're
127declaring such data structures at compile time, there is no current
128user to select which language to use for localization. Thus, we
129cannot call C<loc()> when declaring C<$RIGHTS> and other similar
130places.
131
132For this reason, F<devel/tools/extract-message-catalog> lets you
133denote translatable strings with comments. That's what the C<#loc_pair>
134comments in the C<$RIGHTS> hash in F<lib/RT/Queue.pm> indicate.
135Since we have those comments, our toolchain will put the rights'
136names and descriptions into F<share/po> files, which enables
137translation by our lovely volunteers. Later on, when RT displays
138information about rights in the web UI, we'll pass the right's name
139through C<loc>, and L<Locale::Maketext> will then be able to find
140our "Superusuario". So although we never used a literal
141C<loc("SuperUser")>, we still get its effects thanks to the
142C<#loc_pair> comments and using C<loc($RightName)>.
143
144C<#loc_pair> is used for declaring that the both the key and value
145of a particular C<< key => value >> pair are translatable. There
146are other markers that you can use.
147
148C<#loc> is used for declaring that a particular string is translatable.
149Its parsing is pretty strict so you can use it to declare that only
150the value of a particular C<< key => value >> pair is translatable.
151
152C<#loc_left_pair> is used for declaring that the I<key> of a
153particular C<< key => value >> pair is translatable. This is of
154very limited usefulness.
155
156C<#loc_right_pair> does NOT exist. C<#loc> works in such cases since
157its parser does not extend beyond the string at the end of a line.
158
159=head1 Development tips
160
161=head2 Setting up a development environment
162
163=head2 Test suite
164
165RT also comes with a fairly complete test suite. To run it, you will
166need to set environment variables to a database user and password which
167can create and drop databases:
168
169 export RT_DBA_USER=root
170 export RT_DBA_PASSWORD=
171
172You'll need to configure RT and make sure you have all the dependencies
173before running tests. To do this in place without installing:
174
af59614d 175 ./configure.ac --with-my-user-group --enable-layout=inplace --enable-developer
84fb5b46
MKG
176 make testdeps
177 make fixdeps
178
179Adjust the relevant database options as necessary if you want to test on
180Postgres, Oracle, or SQLite. The default is MySQL.
181
182To run the test suite:
183
184 make test
185
186If you have multiple processors, you can run the test suite in parallel,
187which will be significantly faster:
188
189 make test-parallel
190
b5747ff2
MKG
191The C<*-trunk> and C<master> branches are expected to always be passing
192all tests. While it is acceptable to break tests in an intermediate
193commit, a branch which does not pass tests will not be merged. Ideally,
194commits which fix a bug should also include a testcase which fails
195before the fix and succeeds after.
84fb5b46
MKG
196
197
198
199=head1 git quickstart
200
201=over
202
203=item 1.
204
205You will first need to obtain a copy of git; this is accomplished via
206C<sudo yum install git> in RedHat and derivatives, or C<sudo apt-get
207install git> for Debian or Ubuntu.
208
209=item 2.
210
211Next, obtain a copy of the RT source from git:
212
213 git clone git://github.com/bestpractical/rt.git
214 cd rt
215
216=item 3.
217
218Configure git to know your name and email address; git uses these when
219it makes commits.
220
221 git config user.email your.email@example.com
222 git config user.name Examp L. Name
223
224=item 4.
225
226Switch to the appropriate point to base your work on; this is generally
227C<origin/> followed by the major version, followed by C<-trunk>. For
228example, if your bug was observed in version 3.8.9, you would choose
229C<origin/3.8-trunk>; if it was in 4.0.0, you would choose
230C<origin/4.0-trunk>. New features should be based on C<origin/master>.
231
232 git checkout --track origin/4.0-trunk
233
234=item 5.
235
236Give your branch a name based on what you are attempting to accomplish.
237We suggest that branch names be lower-case and separate words with
238dashes, but this branch name is purely for your own reference.
239
240 git branch -m gnupg-encryption
241
242=item 6.
243
244Edit the source tree to make your changes. A few commands you may find
245useful in doing so are listed below.
246
247To see what files you have changed:
248
249 git status
250
251To see a line-by-line list of changes:
252
253 git diff
254
255To revert a file to the original version:
256
257 git checkout path/to/file
258
259To revert only individual parts of a file:
260
261 git checkout -p path/to/file
262
263See L</Development tips> for more tips for working with the RT codebase.
264
265=item 7.
266
267Check that you have no extraneous changes using C<git diff>, then commit
268your changes:
269
270 git commit -a
271
272You will be prompted to type your commit message. The first line should
273be a short (E<lt> 80 character) summary of the changes, followed by a
274blank line, followed by a longer description, if necessary. The commit
275message should not simply restate the diff of which lines were added and
276subtracted, but should rather explain B<what> those changes accomplish,
277and B<why> they are desired.
278
279If your changes are easily split into multiple components, you may wish
280to split your changes into more than one commit; simply return to step 6
281and repeat the with the next related change. If your changes are B<not>
282related to each other, you should submit them separately; finish step 9,
283then start over from step 4.
284
285=item 8.
286
287Save your commits to patch files:
288
289 git format-patch @{u}
290
291This will print out the names of the files as it creates them.
292
293=item 9.
294
295Attach these files to an email using your standard email client, and
296send it to C<rt-devel@bestpractical.com>.
297
298=back
299
300If you have another bug or feature to implement, simply restart the
301process at step 4.
302
303=cut