h1. continuous4r



h2. <br/>What is it ?

continuous4r is a continuous integration tool for Ruby on Rails. With it, you can aggregate reports of the best analysis, quality, and tests tools for Ruby on Rails. By just launching one Rake task and customizing a XML file describing your project, continuous4r builds for you an entire website in a Maven-like form/design.

h2. Requirements

<ul>
	<li>RubyGems</li>
	<li>rails (erb)</li>
	<li>hpricot</li>
	<li>XmlElements</li>
</ul>


h2. Installing

<pre syntax="ruby">[sudo] gem install continuous4r</pre>

h2. Release notes for 0.0.4 version

<ul>
	<li>Major bug fixes on rcov and changelog builder (differences found on svn with the type of checkout http:// or svn://).</li>
	<li>Tests made on various projects, and notableously to a big one (Redmine).</li>
	<li>Introduction of reporting quality indicators (will be completed for 0.1.0).</li>
	<li>The release of 0.0.5 will be here very shortly, this release is here for build capability.</li>
</ul>

h2. Release notes for 0.0.3 version

<ul>
	<li>Major bug fixes on rcov, ZenTest, tests, and changelog builders.</li>
	<li>Various bug fixes on gems and tasks management.</li>
	<li>Tests made on other projects than mine !!! (Apologies, everyone).</li>
</ul>

h2. Release notes for 0.0.2 version

<ul>
	<li>Full Windows support, and no need for the user to define the HOME environment variable.</li>
	<li>Only quality and code-related tools kept (goodbye Capistrano, httperf, railroad...).</li>
	<li>No need to create the project file from scratch now, type 'rake continuous4r:init' in your Rails project directory, and there you go.</li>
	<li>Full extensibility : the tasks are now defined in [task]_builder.rb files, and instanciated dynamically.</li>
	<li>Full refactoring (Ruby and HTML/RHTML parts).</li>
	<li>Git support added.</li>
	<li>HTTP Proxy support (for those who are constrained by a proxy).</li>
	<li>No need to have eruby installed, now uses the Rails erb compiler.</li>
	<li>HTML global template fixes.</li>
	<li>No need to define or configure your tasks anymore.</li>
</ul>

h2. The basics

h3. Preparing your project

In order to have access to continuous4r Rake tasks, you must open your Rakefile, and add to the end :

<pre syntax="ruby">require 'continuous4r'</pre>

h3. Initializing your project

In order to initialize your project, you must create your continuous4r-project.xml file. 
Just type this command and the file will be created :

<pre syntax="shell">rake continuous4r:init</pre>

Here is the content of this file, you can customize it to suite your needs :

<pre syntax="xml"><project name="FIXME project name" auto-install-gems="true" 
    auto-install-tools="true" ignore-tests-failures="true">
    <description>FIXME project description</description>
    <url>FIXME project URL</url>
    <logo>FIXME Logo URL</logo>
    <company>
        <denomination>FIXME your company name here</denomination>
        <url>FIXME your company website URL here</url>
        <logo>FIXME your company logo URL here</logo>
    </company>
    <members>
        <member id="FIXME user login" name="FIXME user name" email="FIXME user email"
            roles="FIXME user roles, separated by commas" 
            company="FIXME company/organisation name"/>
    </members>
    <bugtracker>
        <tracker_type>[Trac|Bugzilla|Mantis|etc...]</tracker_type>
        <tracker_url>BUGTRACKER_URL</tracker_url>
        <tracker_account_create>BUGTRACKER_URL_ACCOUNT_CREATION</tracker_account_create>
        <search>BUGTRACKER_URL_SEARCH_TICKETS</search>
        <url>BUGTRACKER_URL_TICKETS_LIST</url>
        <add>BUGTRACKER_URL_TICKET_ADD</add>
    </bugtracker>
    <!-- Gems mandatory for your project -->
    <gems repository="http://gems.rubyforge.org/gems/">
        <gem name="GEM_NAME" version="GEM_VERSION"/>
    </gems>
</project>
</pre>

h3. Building your project

When your project file is suitable, type :

<pre syntax="shell">rake continuous4r:build</pre>

When the build is finished, you can find your site in the RAILS_ROOT/tmp/continuous4r directory.


h2. Features

h3. Proxy configuration

If you are behind a HTTP proxy within your company, you can configure it with a simple YAML file. 
Create a file named proxy.yml within your USER_HOME/.continuous4r directory, with the following content :

<pre syntax="yaml">proxy:
  server: my.proxy.server
  port: my_port
  login: my_login
  password: my_password
</pre>

When you will run the build task, if there is a need for continuous4r to find something on the internet (via Rubygems), it will automatically use this configuration.

h3. CruiseControl.rb integration

If you heard about Continuous Integration, and are a fan of <a href="http://cruisecontrolrb.thoughtworks.com" target="_blank">CruiseControl.rb</a>, just customize your project to build the 'continuous4r:build' Rake task, and a 'continuous4r' artifact will appear on your build page.

h3. Running tests

By default the behaviour of continuous4r is to ignore the fact that there are failures in your tests (because the failures are noticed within the tests report).

If you want continuous4r to stop on tests failures, then you must set the "ignore-tests-failures" flag to false in your project file.

h3. Tasks

continuous4r built-in tasks are the core of the gem. They produce reports with some of the best code-related tools for Ruby on Rails. These tasks are described below :

h4. dcov

<a href='http://dcov.rubyforge.org' target='_blank'>Dcov</a> task produces a report related to the coverage of your Ruby documentation (rdoc). If there is a class, a module or a method which is not documented, this task finds it and reports it.

Screenshot :

<a href='images/dcov.png' target='_blank'><img width='200' height='130' src='images/dcov.png' border='0' /></a>

h4. rcov

<a href='http://eigenclass.org/hiki/rcov' target='_blank'>Rcov</a> is a tool which produces a report for the coverage of your Ruby code against you tests.

Screenshot : 

<a href='images/rcov.png' target='_blank'><img width='200' height='150' src='images/rcov.png' border='0' /></a>

h4. rdoc

Produces your project documentation.

<a href='images/rdoc.png' target='_blank'><img width='200' height='80' src='images/rdoc.png' border='0' /></a>

h4. stats

Produces what you get if you run 'rake stats', but in HTML format.

<a href='images/stats.png' target='_blank'><img width='200' height='100' src='images/stats.png' border='0' /></a>

h4. changelog

Produces a HTML report of your code changes in your favorite source content manager. <a href='http://www.git-scm.com' target='_blank'>Git</a> and <a href='http://subversion.tigris.org' target='_blank'>Subversion</a> are supported.

Screenshot :

<a href='images/changelog.png' target='_blank'><img width='200' height='80' src='images/changelog.png' border='0' /></a>

h4. flog

<a href='http://ruby.sadi.st/Flog.html' target='_blank'>Flog</a> is a tool which measures the complexity of your Ruby code.

Screenshot :

<a href='images/flog.png' target='_blank'><img width='200' height='150' src='images/flog.png' border='0' /></a>

h4. xdoclet

A task which transforms your Ruby files in HTML format with syntax highlighting support. This task is used via links in other tasks (look flog screenshot for example).

Screenshot : 

<a href='images/xdoclet.png' target='_blank'><img width='200' height='150' src='images/xdoclet.png' border='0' /></a>

h4. flay

<a href='http://ruby.sadi.st/Flay.html' target='_blank'>Flay</a> task finds duplicates in your Ruby code.

Screenshot : 

<a href='images/flay.png' target='_blank'><img width='200' height='150' src='images/flay.png' border='0' /></a>

h4. reek

<a href='http://wiki.github.com/kevinrutherford/reek' target='_blank'>Reek</a> is code smell detector for Ruby. If there is something bad in your code, it tells you.

Screenshot :

<a href='images/reek.png' target='_blank'><img width='200' height='150' src='images/reek.png' border='0' /></a>

h4. roodi

<a href='http://roodi.rubyforge.org' target='_blank'>Roodi</a> parses your Ruby code and warns you about design issues.

Screenshot :

<a href='images/roodi.png' target='_blank'><img width='200' height='150' src='images/roodi.png' border='0' /></a>

h4. saikuro

<a href='http://saikuro.rubyforge.org' target='_blank'>Saikuro</a> analyzes the cyclomatic complexity of your Ruby code.

Screenshot :

<a href='images/saikuro.png' target='_blank'><img width='200' height='150' src='images/saikuro.png' border='0' /></a>

h4. tests

Task to run your tests and make a report with details (type, success/failure, result).

Screenshot : 

<a href='images/tests.png' target='_blank'><img width='200' height='100' src='images/tests.png' border='0' /></a>

h4. zentest

<a href='http://zentest.rubyforge.org/ZenTest/' target='_blank'>ZenTest</a> is a test tool. It runs a Ruby file against its test file, and generates a convention-delta report if your tests are not good enough.

Screenshot :

<a href='images/zentest.png' target='_blank'><img width='200' height='150' src='images/zentest.png' border='0' /></a>


h2. Help needed

This version 0.0.2 has many improvements, but is still a pre-RC version of continuous4r. I'm planning on orienting the gem to collect some statistics about the tasks, and make a global quality report with graphs.
I'm searching for volunteers to test, or work on this tool. With a more substancial amount of quality and work, this tool will be really great.

h2. License

This code is free to use under the terms of the MIT license. 

h2. Contact

Comments are welcome. Send an email to "Vincent Dubois":mailto:duboisv@hotmail.com,
or post a message on the <a href="http://rubyforge.org/forum/forum.php?forum_id=19721" target="_blank">forum</a>.