Add some documentation around the CI nodes
[buildr.git] / doc / contributing.textile
1 ---
2 layout: default
3 title: Contributing
4 ---
5
6 Buildr is a community effort, and we welcome all contributors.  Here's your chance to get involved and help your fellow developers.
7
8 h2(#involved).  Getting involved
9
10 All our discussions are done in the open, over "email":mailing_lists.html, and that would be the first place to look for answers, raise ideas, etc.  For bug reports, issues and patches, "see below":#bugs.
11
12
13 h2(#mailing_lists).  Mailing Lists
14
15 We run two mailing lists, the "users":http://buildr.markmail.org/search/list:users mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it.  There's the "dev":http://buildr.markmail.org/search/list:dev mailing list for talking about development of Buildr itself. There's also "commits":http://buildr.markmail.org/search/list:commits mailing list for following SVN commits and JIRA issues.
16
17 Check the "mailing lists":mailing_lists.html page for more information on subscribing, searching and posting to the mailing list.
18
19
20 h2(#irc).  Internet Relay Chat
21
22 We are live on IRC under the buildr channel on irc.freenode.net, with a broad coverage of the US timezone. We tend to idle there, so feel free to ping the channel owner (toulmean) to make noise.
23
24 Our "conversations": are logged by the "echelog":http://echelog.matzon.dk/logs/browse/buildr/1279663200 and "irclogger":http://irclogger.com/buildr/ bots. If you're really curious, we also have "activity statistics":http://echelog.matzon.dk/stats/buildr.html
25
26 Sincere thanks to Matzon and Christopher Schneider for setting these up!
27
28
29 h2(#bugs).  Bugs (aka Issues)
30
31 We really do try to keep bugs to a minimum, and anticipate everything you'll ever want to do with Buildr.  We're also, not perfect.  So you may have found a bug, or have an enhancement in mind, or better yet, a patch to contribute. Here's what you can do.
32
33 If it's a bug, enhancement or patch, add it to "JIRA":http://issues.apache.org/jira/browse/Buildr.  For trivial stuff, that's good enough.
34
35 If it needs more attention, start a discussion over on the mailing list.  We will still use JIRA to log the progress, but the mailing list is a better place for talking things through.
36
37 When reporting a bug, please tell us which version of Ruby, Buildr and Java you are using, and also which operating system you are on:
38
39 {% highlight sh %}
40 $ ruby --version
41 $ buildr --version
42 $ java --version
43 {% endhighlight %}
44
45
46 h2(#wiki).  Community Wiki
47
48 "Our community Wiki":http://cwiki.apache.org/confluence/display/BUILDR/Index.
49
50
51 h2(#code).  Contributing Code
52
53 Yes, please.
54
55 If you have a patch to submit, do it through "JIRA":http://issues.apache.org/jira/browse/Buildr.  We want to make sure Apache gets the right to use your contribution, and the JIRA upload form includes a simple contribution agreement.  Lawyer not included.
56
57 h3.  The Perfect Patch
58
59 If you want to get your patch accepted quickly:
60
61 #  Provide a good summary of the bug/fix.  We use that to decide which issue we can do quickly, and also copy and paste it into the changelog.
62 #  Provide short explanation of what failed, under what conditions, why, and what else could be affected by the change (when relevant).  The helps us understand the problem and move on to the next step.
63 #  Provide a patch with relevant specs, or a fix to incomplete/broken specs. First thing we have to do is replicate the problem, before applying the change, and then make sure the change fixes that problem.  And we need to have those specs in there, they make sure we don't accidentally break it again in the future.
64 #  Provide a patch with the fix/change itself.  Keep it separate from the specs, so it's easy to apply them individually.
65
66 If you don't know how to fix it, but can at least write a spec for the correct behavior (which, obviously would fail), do just that.  A spec is preferred to a fix.
67
68 h3.  Working on a new feature?
69
70 If you want to work on a cool new feature, but not quite ready to submit a patch, there's still a way you can get the Buildr community involved.  We're experimenting with using Git for that.  You can use Git to maintain a fork of Buildr that can keep up with changes in the main branch (tip: use @git rebase@), while developing your own changes/features on it.
71
72 That way you can get other people involved, checking out the code, and eventually merge it back with the main branch.  Check out the "Git section":#git below and the post "Git forking for fun and profit":http://blog.labnotes.org/2008/04/30/git-forking-for-fun-and-profit/.
73
74
75 h2(#edge).  Living on the edge
76
77 Did we mention Buildr is an open source project?  In fact, when you install Buildr you get all the source code, documentation, test case and everything you need to use it, extend it and patch it.  Have a look in your Gem directory.
78
79 h3(#svn).  SVN
80
81 But if you want to work with the latest and greatest, you'll want to check out "Buildr from SVN":http://svn.apache.org/repos/asf/buildr:
82
83 {% highlight sh %}
84 $ svn co http://svn.apache.org/repos/asf/buildr/trunk buildr
85 {% endhighlight %}
86
87 You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/buildr.
88
89 h3(#git).  Git
90
91 Not a fan of SVN?  We understand.  You can also use the "official Apache Git clone.":http://git.apache.org  This clone is maintained by the ASF and kept in sync with the SVN repository (though, in practice there may be some delay in cloning recent commits).  Apache's Git hosting supports both git:// and http:// protocols (you should use git:// if at all possible as it is faster than http://):
92
93 {% highlight sh %}
94 $ git clone git://git.apache.org/buildr.git
95 # or...
96 $ git clone http://git.apache.org/buildr.git
97 {% endhighlight %}
98
99 If you want to learn more about Git, you can start by watching Scott Chacon’s "Git presentation":http://en.oreilly.com/rails2008/public/asset/attachment/2816 (PDF), or any of the "Git screencasts":http://www.gitcasts.com/.  For more, there's also the "Git Internals book":http://peepcode.com/products/git-internals-pdf.
100
101 And keep this "Git cheat sheet":http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png close at hand. Very useful.
102
103 h4. GitHub
104
105 You are also welcome to fork or clone the "Buildr repository on GitHub":http://github.com/apache/buildr.  This repository is just an exact mirror of the official Apache Git clone referenced above (updated every 30 minutes).  Some of the core committers also maintain their own forks of Buildr on GitHub, often containing experimental and in-progress development slated for eventual inclusion into the SVN.  For reference, they are listed below:
106
107 * "Assaf Arkin":http://github.com/assaf/buildr
108 * "Victor Hugo Borja":http://github.com/vic/buildr
109 * "Daniel Spiewak":http://github.com/djspiewak/buildr
110
111 h3. Working with Source Code
112
113 To install Buildr from the source directory:
114
115 {% highlight sh %}
116 $ cd buildr
117 $ rake setup install
118 {% endhighlight %}
119
120 When using Buildr for JRuby:
121
122 {% highlight sh %}
123 $ cd buildr
124 $ jruby -S rake setup install
125 {% endhighlight %}
126
127 The _setup_ task takes care of installing all the necessary dependencies used for building, testing and running Buildr. Once in a while we upgrade or add new dependencies, if you're experiencing a missing dependency, simply run @rake setup@ again.
128
129 The _install_ task creates a Gem in your working directory (_pkg/_) and install it in your local repository. Since Ruby Gems uses version numbers to detect new releases, if you installed Buildr this way and want to upgrade to the latest official release, you need to use @gem install buildr@ rather than @gem upgrade@.
130
131 Both _setup_ and _install_ tasks use the @sudo@ command on platforms that require it (i.e. not Windows), so there's no need to run @sudo rake@ when working with the Buildr source code.
132
133
134 h3. Using development build
135
136 Occasionally we'll make development builds from the current code in trunk/head. We appreciate if you can take the time to test those out and report any bugs. To install development builds, use the Gem repository at @people.apache.org/~assaf/buildr/snapshot@:
137
138 {% highlight sh %}
139 gem source --add http://people.apache.org/~assaf/buildr/snapshot/
140 {% endhighlight %}
141
142 Since Ruby Gems uses version numbers to detect new releases, if you installed Buildr from a snapshot and want to upgrade to a newer snapshot or the latest official release, you need to use @gem install buildr@ rather than @gem upgrade@.
143
144 If you want to go back to using the RubyForge releases:
145
146 {% highlight sh %}
147 gem source --remove http://people.apache.org/~assaf/buildr/snapshot/
148 gem install buildr
149 {% endhighlight %}
150
151
152 h2(#testing).  Tested and Documented
153
154 Two things we definitely encourage!
155
156 h3.  Testing/Specs
157
158 Obviously we won't turn down patches, but we'll love you even more if you include a test case.  One that will fail without the patch, and run successfully with it.  If not for our love, then think of the benefit to you: once we add that test case, we won't accidentally break that feature in the next release.
159
160 We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test framework.  The main difference between RSpec and xUnit is that RSpec helps you formulate test cases in terms of specifications: you describe how the code should behave, and run RSpec to make sure it matches that specification.
161
162 You can run an individual specifications using the @spec@ command, for example:
163
164 {% highlight sh %}
165 $ spec spec/compiler_spec.rb
166 $ spec spec/compiler_spec.rb -l 409
167 {% endhighlight %}
168
169 The first command will run all the specifications in @compiler_spec@, the second command will run only the specification identified by line 409 of that file. You can use line numbers to point at a particular specification (lines starting with @it@), or set of specifications (lines starting with @describe@). You can also use the @-e@ command line option to name a particular specification.
170
171 To make sure your change did not break anything else, you can run all the specifications (be patient, we have a lot of these):
172
173 {% highlight sh %}
174 $ rake spec
175 {% endhighlight %}
176
177 If you get any failures, you can use @rake failed@ to run only the failed specs, and repeat until there are no more failed specs to run. The list of failed specs is stored in the file _failed_.
178
179 We always @rake spec@ before making a release.
180
181 For full test coverage:
182
183 {% highlight sh %}
184 $ rake coverage
185 {% endhighlight %}
186
187 Specification and coverage reports are HTML files you can view with a Web browser, look for them in the _reports_ directory. You can also check out the "RSpec report":specs.html and "test coverage":coverage/index.html we publish with each release.
188
189
190 h2(#docs).  Documentation
191
192 Yes, we do make typos, spelling errors and sometimes we write things that don't make sense, so if you find a documentation bug, or want to help make the documentation even better, here's the way to do it.
193
194 For simple typos and quick fixes, just send a message to the mailing list or log an issue in JIRA.
195
196 If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch.  Making documentation patches is fairly easy.  All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from Git/SVN, edit, and @svn diff@ to create a patch.
197
198 We use "Textile":http://www.textism.com/tools/textile/ as the markup language, it takes all of a few minutes to learn, it's intuitive to use, and produces clean HTML.  You can learn it all in a few minutes from the "Textile Reference Manual":http://redcloth.org/textile.  Also check out the "Textile Quick Reference":http://hobix.com/textile/quick.html.
199
200 Syntax highlighting handled by "Pygments":http://pygments.org.  Use the special @highlight@ tag to separate code sample from the rest of the text and to tell Pygments which language to use.  For example:
201
202 <notextile><pre>
203 &#123;&#37; highlight ruby &#37;&#125;
204 define 'project' do
205   # Just a sample
206 end
207 &#123;&#37; endhighlight &#37;&#125;
208 </pre></notextile>
209
210 Have a look at existing documentation to see writing conventions, specifically:
211
212 * Separate paragraphs with two newlines.
213 * Use one newline only if you need a &lt;br&gt; tag, otherwise, no newlines inside the paragraph.
214 * When creating a new page, don't forget the YAML premable at the top (Jekyll needs the page title and layout).
215 * The layout uses H1 to render the page title; only use H2 through H4 for the page content.
216 * Use H2 headers for the major page sections.  Give each H2 header a unique ID so the table of contents can link to it.
217 * Separating sentences with two spaces, just a convenience when editing in a text editor using monospaced fonts.
218 * If in doubt, ask.
219
220 To go from Textile to HTML we use "Jekyll":http://github.com/mojombo/jekyll.  You can use the @jekyll@ rake task to transform the files under @doc@ and create a copy of the Web site in the directory @_site@.  For example:
221
222 {% highlight sh %}
223 $ rake jekyll
224 $ open _site/index.html
225 {% endhighlight %}
226
227 There is no live editing, but you can run @rake jekyll auto=true@, and when you update and save a Textile page it will regenerate the corresponding HTML page.
228
229 To go from HTML to PDF we use "PrinceXML":http://www.princexml.com/.  The target file @buildr.pdf@ is generated by first running Jekyll and then merging the generated HTML pages into a single PDF document.  For example:
230
231 {% highlight sh %}
232 $ rake buildr.pdf
233 $ open buildr.pdf
234 {% endhighlight %}
235
236
237 h2(#ci).  Continuous Integration
238
239 Buildr uses the Jenkins continuous integration tool to perform builds, run tests and report back on problems when changes are made to the source code repository.
240
241 The care and feeding of the "CI Jobs":https://builds.apache.org/view/A-F/view/Buildr is the responsibility of the committers. To get access to configure the CI Jobs a committer needs to follow the directions on the "jenkins":http://wiki.apache.org/general/Hudson documentation site.
242
243 You may also need to coordinate with the Apache infrastructure team to get accounts on the actual slave hosts that run the CI jobs. This access may be required to install tools and gems required to run the CI jobs. The main slave host to get access to is vesta.apache.org at the time of writing. You can also log on to the slave host, impersonate hudson and manually run tasks when you are attempting to track down build problems. Of course to impersonate hudson you will need to learn how to use "OPIE.":http://apache.org/dev/freebsd-jails
244
245 h3(#cilinux).  Linux Setup
246
247 The tests on the Linux hosts rely on "RVM":https://rvm.io/ to setup the ruby environment. At the time of writing the Linux/x86 nodes that Apache uses for CI are based of the old "Ubuntu 10.04.4 LTS (Lucid Lynx)" operating system. As it is a relatively old operating system, it requires a little bit of manual intervention to install RVM on the node. We have installed the required tools on vesta.apache.org manually. The script looks something like;
248
249 {% highlight sh %}
250 ssh my_username@vesta.apache.org
251 sudo su - hudson
252
253 curl -L https://get.rvm.io | bash -s stable
254 rvm reload
255 rvm pkg install readline
256 rvm pkg install iconv
257 rvm pkg install curl
258 rvm pkg install openssl
259 rvm pkg install zlib
260 rvm pkg install autoconf
261 rvm pkg install ncurses
262 rvm pkg install pkgconfig
263 rvm pkg install gettext
264 rvm pkg install glib
265 rvm pkg install mono
266 rvm pkg install llvm
267 rvm pkg install libxml2
268 rvm pkg install libxslt
269 rvm pkg install libyaml
270 rvm install ruby-1.8.7-p358
271 rvm install ruby-1.9.2-p320
272 rvm install jruby-1.6.7
273 rvm install ruby-1.9.3-p194
274 {% endhighlight %}
275
276 It should also be noted that jruby-1.6.7 release has a native library that is compiled using a more modern version of libc than is available on this variant of the operating system. We could download the source release and recompile the library but instead we have just avoided the need for any use of the ruby native interface library in our CI infrastructure.
277
278 h3(#ciwindows).  Windows Setup
279
280 The ci infrastructure on the windows host (hudson-win.apache.org) is a little fragile. First you need to RDP in and download the support libraries. We have manually installed the tools in the following locations. Note: it is important to make the locations read-write access to the hudson user.
281
282 {% highlight sh %}
283 F:\hudson\tools\Ruby193-p194
284 F:\hudson\tools\Ruby192-p290
285 F:\hudson\tools\Ruby187-p370
286 F:\hudson\tools\jruby-1.6.7
287 F:\hudson\tools\scala-2.9.0.1
288 {% endhighlight %}
289
290 WARNING: Several attempts were made to use GEM_HOME to install the dependent gems for each test in a separate location but we were unable to figure out the mechanisms via which sub-shells would inherit the paths and the ability to run tools such as rspec.
291
292 h2(#contributors).  Contributors
293
294 Here is the list of people who are actively working and committing on Buildr:
295
296 *"Assaf Arkin":http://labnotes.org* (assaf at apache.org)
297
298 Started working on Buildr because Maven was too much pain and Rake wasn't enough.  Assaf has been hanging around Apache since 1999, as founding contributor to XML Apache, Ode and Buildr.  Assaf is also co-author of "Ruby In Practice":http://manning.com/mcanally/.
299
300 *Alex Boisvert*
301
302 Came to Buildr as a refuge from the Maven Uncertainty Principle.  Alex has been working mostly on the Scala integration and believes Ruby scripting is a great complement to statically typed languages.
303
304 *"Matthieu Riou":http://offthelip.org*
305
306 *Victor Hugo Borja* (vborja at apache.org)
307
308 Currently a Java Developer at "http://jwmsolutions.com":http://jwmsolutions.com, Victor has been enjoying and using Apache's software since 1999 when he started with Java, now he prefers programming Ruby and is happy to help on Apache's first ruby project.
309
310 *Lacton* (lacton at apache.org)
311
312 A test-infected developer since 2001, Lacton yearns for a development infrastructure that would shorten feedback loops so much that testing, building, refactoring and committing would feel as easy and natural as breathing air.
313
314 *"Daniel Spiewak":http://www.codecommit.com/blog* (djspiewak at apache.org)
315
316 Daniel originally came to Buildr in search of a Scala build tool which was better than Ant.  He got more than he bargained for.  Now, he works to advance Buildr as the absolute best tool for supporting Scala development.
317
318 *"Antoine Toulme":http://www.lunar-ocean.com/* (toulmean at apache.org)
319
320 Antoine used Buildr first as an excuse to evade in Ruby land, creating plugins for Debian packaging, GWT compilation, or the NSIS installer. His main area of interest is the resolving of dependencies in the OSGi world. He works on making Buildr a standalone rock solid tool.
321
322 *Peter Donald*
323
324 Peter already used rake to automate jobs in his ruby and java projects. When it came time to upgrade that home grown ant/java/rake build system Buildr seemed the perfect match.