This is the first blog entry in a series about the process of going from idea to running software, while following all of the practices that we praise and push at our clients.
Tempo
At Integrallis we have been using an open source PHP-based Time Tracking Tool for a few years now. Don't get me wrong, we are thankful that this tool was out there to help us run our business but it's missing several features that we consider key, we don't have anybody on staff that knows PHP and the app is just plain ugly ;-) So we decided to write our own, Yeah, yeah we are suffering from the not invented here syndrome but in my defense I thought it would make for a nice series of blog entries/tutorials on how we are approaching the building of this application using Ruby on Rails. So let's start by describing in just a few paragraphs what is that we are looking to build.
"Tempo is a project based time tracking web application targeted primarily at small consulting firms and independent consultants"
To track the development of Tempo we are using the agile project management tool Savila created by our friends at Caimito Technologies. We are starting with a few simple user stories that should take us to the basic functionality required.
The initial user stories revolve around the basics of a time tracking system, basic project/tasks management and the authentication system.
Getting Started
Before we get to the user stories let's make sure that you have everything that you need to get started. We are using Rails version 1.2.3, Ruby 1.8.6 and MySQL 5.0.24.
There are countless Rails tutorials on the web. If you've never worked with Rails I suggest you go through one the top RoR tutorials
I have created a skeleton rails application (hopefully you know how to do that by know but just in case you don't, simply type:
/>rails tempoWe can use the about script to see what we have so far...
/> script/about About your application's environment Ruby version 1.8.6 (i686-darwin8.9.1) RubyGems version 0.9.2 Rails version 1.2.3 Active Record version 1.15.3 Action Pack version 1.13.3 Action Web Service version 1.2.3 Action Mailer version 1.3.3 Active Support version 1.4.2 Application root /Users/bsbodden/Documents/projects/tempo Environment development Database adapter mysql Database schema version 4
At this point you should be able to get your skeleton application running.
Initial User Stories
The table and the Savila screenshot below show the user stories that we will be tackling on "Sprint #1" of the Tempo development. The duration of the Spring should be around 2 weeks (I'm building Tempo on my spare time ;-)
| Story Id | Short Description | Status | Complexity | Business Value |
| TMPO-4 | Login into the site | OPEN | 10 points | Business Critical |
| TMPO-15 | Site Admin adds global Activities | OPEN | 20 points | Business Critical |
| TMPO-19 | Site Administrator Creates a Project Owner Account | OPEN | 20 points | Business Critical |
| TMPO-21 | Site Administrator creates a User Account | OPEN | 20 points | Business Critical |
| TMPO-25 | Site Admin creates a Project | OPEN | 20 points | Business Critical |
| TMPO-27 | Site Administrator assigns a User as Project Owner for a given Project | OPEN | 20 points | Business Critical |
| TMPO-29 | User enters Time | OPEN | 40 points | Business Critical |
Managing Plug-ins with Piston
Before we start downloading and installing plugins I decided that I needed a better way to manage the plugins in my application. To accomplish this I installed Piston. Piston enables you to better manage the vendor branch. It does a better and simpler job that using svn:externals, and you can "install" plugins into your vendor/plugins directory and lock them to a certain version.
Install Piston
Install the piston gem by using the following command:
gem install -y piston Bulk updating Gem source index for: http://gems.rubyforge.org Successfully installed piston-1.3.3
Restful Authentication
Since a lot of the initial stories revolve around a User, a good starting point is to get an authentication system going. Since I want to also make Tempo a Restful Rails application. I will based my authentication system on the Restful Authentication plugin, which is a restful version of the familiar actsas_authenticated. Let's use Piston to import the restfulauthentication plugin and create our user model and sessions controller. I find that very often in web-based application the User model is a good starting point from where to flesh out the rest of the system.
Install Restful Authentication Plugin
/> piston import http://svn.techno-weenie.net/projects/plugins/restful_authentication vendor/plugins/restful_authentication Exported r2983 from 'http://svn.techno-weenie.net/projects/plugins/restful_authentication' to 'vendor/plugins/restful_authentication'
Generate User model and the Sessions controller
/> script/generate authenticated user sessions
----------------------------------------------------------------------
Don't forget to:
- add restful routes in config/routes.rb
map.resources :users
map.resource :session
Rails 1.2.3 may need a :controller option for the singular resource:
- map.resource :session, :controller => 'sessions'
Try these for some familiar login URLs if you like:
map.signup '/signup', :controller => 'users', :action => 'new'
map.login '/login', :controller => 'sessions', :action => 'new'
map.logout '/logout', :controller => 'sessions', :action => 'destroy'
----------------------------------------------------------------------
exists app/models/
exists app/controllers/
exists app/controllers/
exists app/helpers/
create app/views/sessions
exists test/functional/
exists app/controllers/
exists app/helpers/
create app/views/users
exists test/functional/
exists test/unit/
create app/models/user.rb
create app/controllers/sessions_controller.rb
create app/controllers/users_controller.rb
create lib/authenticated_system.rb
create lib/authenticated_test_helper.rb
create test/functional/sessions_controller_test.rb
create test/functional/users_controller_test.rb
create app/helpers/sessions_helper.rb
create app/helpers/users_helper.rb
create test/unit/user_test.rb
create test/fixtures/users.yml
create app/views/sessions/new.rhtml
create app/views/users/new.rhtml
create db/migrate
create db/migrate/001_create_users.rb
/>
As the plugin clearly suggests I added the following code to my routes.rb file in /config
# Restful Authentication routes
map.resources :users
map.resource :session, :controller => 'sessions'
# Map to familiar URLs
map.signup '/signup', :controller => 'users', :action => 'new'
map.login '/login', :controller => 'sessions', :action => 'new'
map.logout '/logout', :controller => 'sessions', :action => 'destroy'Ok now we have basic authentication and some tests to prove that. We could go ahead and add out changes to the User model but first let's run the migration in development and make sure that all the tests that the plugin generator created pass.
If you haven't done it yet, go ahead and configure the database and create the mysql instance for tempo_development
Running our first migration for Tempo
>rake db:migrate
/> rake db:migrate
(in /Users/bsbodden/Documents/projects/tempo)
== CreateUsers: migrating =====================================================
-- create_table("users", {:force=>true})
-> 0.0591s
== CreateUsers: migrated (0.0593s) ============================================
Running the existing tests
/> rake (in /Users/bsbodden/Documents/projects/tempo) Started .............. Finished in 0.219704 seconds. 14 tests, 26 assertions, 0 failures, 0 errors
Yay! You can test the app (assuming that you've started the server) by pointing your browser to http://localhost:port /signup /login /logout
Now the real work starts, in the next installment of this series we will tackle the development of the domain using DDD (Domain Driven Development) and TDD (Test Driven Development).
