Trevor has renamed the Image model to Asset to avoid “image_path” namespace conflicts. Also, Dan Quellhorst caught a security issue in the default “user.to_xml” that was showing the passwords. Install instructions were culled from the various comments and moved to README.

Finally, I’ve tagged version 3 as stable, and we’ll backport any critical bugs to this branch, but no new features, so you can safely use it with piston. We’ll create any schema changes as new migrations in stable branch (it’s up to you to fit them to your project).

Trunk will continue to be developed and migrations will not be back-compatible; that is, if we change the user or asset tables, we won’t create new migrations. As we get enough features to warrant a release, it’ll be tagged.

You can download tarballs or view the sourcecode online at our old-school-style site,

http://sample.caboo.se/

Update: Please see http://sample.caboo.se/ for the latest version of our sample apps.

Get it here:

svn://caboo.se/plugins/court3nay/empty_apps/restful_auth_rspec

Contact the author (you'll need to add .com to the email):

<court3nay+sra@gmail>

Requirements:

You'll need a few gems.

• rspec
• image_science OR rmagick

Changeset:

• removed 'with_scope' and replaced it with protocool's awesome polymorphic controller code.
• added his resource_fu plugin for restful helper methods

The most recent changes are due to Trevor/protocool, the author of the resource-fu plugin. It seems like nested resources in a polymorphic form are extremely difficult to implement in a clean manner.

Here's a snippet of code:

delegate :images, :to => '@attachable'
helper_method :images

def load_image
  @image = images.find(params[:id])
end

Beautiful. It relies on the images controller being an abstract class, defining @attachable in the inherited class, and delegating "images" helper method to that @attachable object.

From the readme:

Caboose Sample App

This is a sample application containing a bunch of useful plugins and code to help you get started quicker.
It is intended to be an example of "better practices", but with the intention of ultimately being "best practice" through collaboration and iterative improvement.

The application implements many of the basic and advanced features I find myself using in every new project:

• a user model with a few extra fields (last login, timezones)
• restful authentication
• simple authorization (can't edit other's profiles)
• full timezone support
• basic views implemented with Yahoo! YUI CSS grids
• behavioral testing with rspec, including good example of mocking in controller specs
• exception notification (remember to change the email address in environment.rb)
• nested resources (user/images) which can easily be extended (e.g. product/images)
• polymorphic image model
• around_filters to set and clear request-specific data

Many of the enhancements to the stock plugins are ripped from my private codebase, as yet unseen by the world :)

TODO:

Sample controllers and models More useful plugins Good examples of ajax Better list of requirements (required gems, etc)

TODONE:

x Polymorphic Image model using attachment_fu

Many of the documentation project patches are being merged as we speak into the rails core. Behold the power of this partially operational battle station!

You can wait for the next release of Rails, or, see the updated API on the caboose edge rails api. Remember that the edge API has all the private (#:nodoc) methods exposed, so don’t operate heavy machinery while under its influence. (As a sidenote, the docs were not actually auto-generating since I moved servers, so I fixed the missing crontab entry)

Hello; it’s time for a quick update on the documentation project. Jamie and I are working hard on getting the “big pieces” documented right now. The idea is that we’ll get ActionView, ActionController, and ActiveRecord well documented, and then go back to the main Rails README and edit it to effectively use the shored up docs in those packages. Jamie is still slaving away on the ActiveRecord documentation (and making good progress!) while I turned out a new README for ActionPack today.

• 7869 : Improved ActionPack README

The patch still needs a few tweaks to the examples (some of them wouldn’t make sense to a newbie), but it’s much better than it was. The target next week will be ActionView::Base and/or ActionController::Base documentation…but that’s next week. :)

It’s fun coming up with the number of ways I can say “Documentation Project update.”

We got a lot done today. We finally meshed on a method template that we’ll use for documenting all methods, and started documenting a lot of methods with it! I tackled the ActionController::Assertions module(s) while Jamie kept hammering away on ActiveRecord. He got the README done (and part of the AR::Base docs) while I got two patches done for the Assertions (and one started for ActionView::Base after restarting to match our decided upon layout for README/::Base docs). Here are the tickets:

• 7747 : Better structured Active Record readme Updated to fix an rdoc formatting error
• 7802 : ActionController::DomAssertions module, explaining what it’s for, better explaining the methods, and providing examples.
• 7803 : ActionController::Assertions module, second patch in an effort to improve these docs.
• 7808 : ActiveRecord::Base, overview is a little rounder but plenty left to go on this one

See you next week. :)

It's time for another documentation project update. This week concentrated on continuing to lay down plans, with the creation of a styles and conventions page that we (and future doc writers) will do our best to adhere to. We also laid plans to create a Rails application to keep track of our Basecamp information rather than giving the public access (since someone keeps ticking off our to-do items...). Here are the patches this week:

• #7656 : ActionView::Helpers::PrototypeHelper documentation
  UPDATED I updated this patch to include documentation of all the JavaScript generated by the methods; I also went back and fixed a few errors in the original documentation and my edits.
• #7722 : ScriptaculousHelper documentation improvements
  The documentation for ScriptaculousHelper assumed (a) that the reader knew what Scriptaculous was and (b) they knew what all the parts did. This patch adds more background information, shows the javascript generated by each method, improves the README, and cleans up the grammar a little bit.

In light of the new README convention we've developed (README's for packages will contain very high level overviews with no examples, Base class documentation will have examples with very little theory and will act as jumping pages to the relevant portions of the documentation) I'm working on a new README and Base class documentation for ActionView (ActionPack) that's about 75% done; Jamie is nearly done with the ActiveRecord documentation in the same vein. Both of those patches should probably make it in next week, which will result in a hefty upgrade to the documentation of those classes/packages.

Also, in the interest of helping out this documentation project, I've developed a tool called dcov (Documentation COVerage) that will report on the documentation coverage of Ruby code files, somewhat similarly to rcov. It basically rips a lot of Ruby parsing code off of Rdoc (which rips its code off of something else ;)) and generates a report on documentation coverage of classes, modules, and methods. Right now, it merely tests for a comment, but soon one day I want to have it crawl the code and test for options hashes and then check for documentation of those, generate documentation stubs, with placeholders for parameter documentation (and eventually any usage of the options hash it can figure out), and more...but that comes with time. I'll post the Rubyforge page when it's in a state ready to be used.

I just wanted to give everyone an update on the documentation project from my and Jamie's work on Monday. Here is a list of the tickets we've submitted so far.

• #7590 : More config comments added to database.yml
  This patch adds a signficant piece of information to database.yml pertaining to configuration.
• #7591 : smtp configuration options added
  Explanation of the smtp options; we're working towards explaining every options hash for every method (ambitious? yes. psychotic? definitely.)
• #7618 : [ACCEPTED] Better documentation on Form Helpers
  Changed the form helper documentation to be more understanding for beginners.
• #7651 : Rake annotations searching only in rxml/rhtml files and not builder/erb files (also fix reference to rhtml file in a doc)
  I was working on replacing any reference to rhtml with erb, but while doing so, I noticed a rake task that searched only for rhtml/rxml files rather than rhtml/erb/rxml/builder. So I fixed that while I was at it.
• #7652 : ActionController::Scaffolding documentation extended and improved
  Greatly extended the Scaffolding documentation, including some information about how to replace scaffolding with your own stuff.
• #7656 : ActionView::Helpers::PrototypeHelper documentation
  This is much improved PrototypeHelper documentation; I'm still working on this patch. I want to add some documentation explaining what gets generated and fix a few little issues here and there.

Jamie also worked on some much improved ActiveRecord::Base documentation (excited to see that!). We're hoping to turn out a few more patches next week. We're currently working on "high level" documentation, but will eventually get down to documenting the minutia such as option hashes and the like. You can stay posted on what we're doing on the Basecamp that Jamie posted to the caboose blog yesterday.

As part of our planning and overall management, I thought it would be a good idea to let everyone have access to the basecamp project we’ve made to keep track of our todos. So if you’d like to check out the todo list for our documentation project, or leave a comment to let us know we’re missing something (which we will be somewhere, so please do), then hop over to our basecamp address and log in with these details:

Caboose Documentation Project Basecamp

• user: guest
• pass: guest

Please be sure not to abuse it or I’ll have to shut down access which would be a shame.

Jamie “fearoffish” has been elbow-deep in the rails API documentation, developing a plan and getting down to the task of actually writing. In the interests of full disclosure, he’ll be getting paid the daily rate of £225 (which is about $450 USD) as will all the documenters.

Part of his first day was spent collaborating with the other author (see below), DHH, and other interested parties, planning out what needs to be documented, and to make sure effort isn’t wasted. Basically, the plan is to write voluminous examples and fix the outdated code. Finally, we trawled through the rails-talk mailing list to find some of the most common questions.

Here are the patches Jamie completed.

• http://dev.rubyonrails.org/ticket/7590 - adding more examples to database.yml
• http://dev.rubyonrails.org/ticket/7591 - adding smtp configuration example to environment.rb. Since smtp is now the default in rails, this one makes sense to have in there
• http://dev.rubyonrails.org/ticket/7618 - better documentation on form helpers. lots of good examples in here.

another author!

Jeremy McAnally is the second author to devote a day a week to the project. You may know him from the “Humble little ruby book”.

Jamie, aka “fearoffish” from the UK, after doing his time in the trenches, comes on board as a part-time caboose blogger and the first documentation project writer.

He’ll be armpit-deep in the API, writing for one (full-time) day a week. Suggestions on where to start? Pick a file or subject matter!

Jamie’s a skilled coder whose rails-fu impressed me while working as one of my contractors last year. He’d started on an open-source book entitled, Getting Started with Rails which proves his writing ability.

Hit us up in the comments with them suggestions!

Are you a writer? There’s still plenty of days left in the week!

I think this is the best starting point so far. http://caboose.stikipad.com/documentation/show/Rails+Cross+Reference >**Problem**: You know what you want to do, but you don’t know what method is appropriate. >**As Is Situation**: Right now, the search of the RAILS API documentation is one way. In other words, the “documenters” decide what goes into the description of a method/class etc. So if they are not thinking of that other usage for a particular class/module/method, you will not find it. Kevin Clark was working on something like this at Rubyconf but never checked it in. A high-level guide to "how to do stuff" with links deep into the API. Any takers?

Professional Author working on rails API

It seems like none of the published Ruby or Rails authors want to actually work on the Rails documentation. Perhaps its the lack of glory, or the fact that there are no residuals. I’ve spoken to most of the well-known, published, ruby or rails authors, and none of them are interested. I even hit up the Ruby guys at Rubyconf in person, and all of them said “Well, I don’t really know rails that much..” I’ve chased up the names: Hal, Chad, Amy, Lucas, Jake, Dave, Obie, David—even the guys who write the blogs and don’t have books out yet. They just don’t wanna do it.

So, the conundrum facing us today is, “Where do we find an author?” I’ve chased all the people I know. There are a few good projects out there worthy of mention; the fearoffish open-source rails book at http://svn.devjavu.com/rails/ is a prime example—but we need your help on this, now, folks. How do you catch a technical writer? How do you interest them?

RDOC project

The idea with this project is to make it simple to make patches to documentation, and to reward those who do. It’s Nearly Done, and the parts that work, work well. We really are fighting against the arcane rdoc format. But if you take a look at the commit logs it’s really just me plugging away. This doesn’t scale, since I don’t actually have that kind of time, and I’m not taking money from the master fund in order to work on it (that’s not what it’s for). Many people requested svn access, and then just didn’t do anything. Others started off strongly and then just disappeared, or have contributed two or three patches. So the app just stagnates, because there isn’t the interest.

What needs to be done?

1. an automated way of posting patches to the core rails trac
2. a fix for editing “class-level” code
3. fix the “plea” code so that people can flag some docs as requiring attention

Sure, people donated so they didn’t have to worry about any of this. But that money is locked in limbo until we have a framework for handing out the cash to the masses (aka doc patches), and/or some decent technical writers willing to put in some time. And no, I will not look at proposals for all of the money to go to one writer. I also will not look at proposals from people who’ve never published a ruby technical document before.

Hook it up in the comments and let’s get the ball rolling. The wiki is at http://caboose.stikipad.com/documentation/

We're powering ahead on the doc project app. Logins are now implemented with open-id, so you can stop writing mopey poetry on your livejournal, or stop mashing refresh on your technorati page, and login to the caboose rdoc app without a password, no setup, nothin'. We've got some awesome layout and css work on the way, courtesy of Amy Hoy and Christi Balan, and a bunch of useful features, like the infamous, "I'm too lazy or noobish to write this myself" button. One of the big issues that came up at Rubyconf was that most of us don't actually use the docs that much, so we find it hard to determine where the biggest need is. This is where that "flag this doc for improvement" feature will come in handy. The app is nearly ready for public consumption, by which I mean, it's not ready at all, but will be Real Soon Now. You really should email me if you want access to the subversion repo and aren't a cabooser.

Please use the wiki - [http://caboose.stikipad.com/documentation](http://caboose.stikipad.com/documentation) - to give us your ideas about how the documentation project can proceed. Thanks.

So, you’re making a living from rails? You should consider putting up $10, or $50, or whatever, to fund a professional to spend some quality time alone with the API documentation. We’re aiming at $5,000 USD. Here’s the paypal button. All the money received at this account will go towards paying one or more people to enhance the Ruby on Rails API. If you want some serious props, please attach your name or fire me an email and we’ll publically celebrate everyone’s contribution. (No, we haven't decided on how this will be achived, but it's likely contributors will get to vote from a handpicked selection of proven and/or skilled documenters) Thanks in advance! (Credit cards accepted..)

Prizes!

When we reach $5,000, we will randomly hand out prizes! So far, we have, to give away: - 2 copies of the [Money Train](http://www.agilewebdevelopment.com/book), from [Ben Curtis](http://bencurtis.com) (building e-commerce apps in rails!) - 2 combo-packs (pdf + dead tree) of [Beginning Ruby on Rails E-Commerce](http://www.amazon.com/gp/product/1590597362/) by Jarkko Laine and Christian Hellsten, __signed__ (if you have anything as an incentive, fire court3nay a gmail)

[0........1.........2.........3.........4.........5]
[OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO] $5 000
[OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO] $10 000
[OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO] $15 000
[OOOOOOOOOOO.......................................] $20 000

Contributors!

- $50 : Amy Hoy [slash7.com](http://slash7.com) - $50 : Phil Hagelberg [technomancy.us](http://technomancy.us) - $100 : Kevin Clark [glu.ttono.us](http://glu.ttono.us) - $25 : Jacob Harris [nimblecode.com](http://nimblecode.com) - $50 : Jamie van Dyke [fearoffish.co.uk](http://fearoffish.co.uk) - $100 : Topfunky Corporation [topfunky.com](http://topfunky.com) - $75 : Matthew Lyon [postsomnia.com](http://postsomnia.com) - $100 : Josh Susser [hasmanythrough.com](http://hasmanythrough.com) - $20 : Scott W Hill - $50 : Damien Tanner [new-bamboo.co.uk](http://new-bamboo.co.uk) - $50 : Corey Donohoe [atmos.org](http://atmos.org) - $250 : Ivey & Brown, Inc. [iveyandbrown.com](http://iveyandbrown.com) - $100 : Lars Pind [pinds.com](http://pinds.com) - $40 : Erik Kastner [metaatem.net](http://metaatem.net) - $80 : Joshua Sierles - $20 : Blake Watters [thatswhatimtalkingabout.org/news/](http://thatswhatimtalkingabout.org/news/) - $20 : Nicholas Dainty - $200 : gravatar.com [gravatar.com](http://gravatar.com) - $50 : Randy Souza - $100 : Chris Wanstrath [errtheblog.com](http://errtheblog.com) - $100 : Lucas Carlson [rufy.com](http://rufy.com) - $125 : Thomas Moertel [blog.moertel.com](http://blog.moertel.com) - $50 : Michael Brian Naberezny [mikenaberezny.com/](http://mikenaberezny.com/) - $100 : Nic Williams [drnicwilliams.com](http://drnicwilliams.com) - $50 : Samuel Smoot - $20 : Pedro Visintin [blogs.onrails.com.ar](http://blogs.onrails.com.ar) - $30 : Ben Curtis [bencurtis.com](http://bencurtis.com) - $100 : PJ Hyett [pjhyett.com](http://pjhyett.com) - $100 : Josh Knowles [joshknowles.com/](http://joshknowles.com/) - $50 : Christ McGrath [octopod.info](http://octopod.info) - $100 : RADsoft [radsoft.com](http://radsoft.com) - $20 : Michael Campbell - $15 : Michael Zatko - $20 : Tieg Zaharia - $33 : Michael Behan - $20 : Steven Luscher [stevenluscherdesign.com/](http://stevenluscherdesign.com/) - $50 : NanoRails [blog.nanorails.com/](http://blog.nanorails.com/) - $10 : Sea Change Nutraceuticals, Inc. - $10 : Jesse Rankin - $100 : Steelpixel, LLC [steelpixel.com](http://steelpixel.com) - $111 : John Weir [smokinggun.com](http://smokinggun.com) - $31 : Blaine Cook - $100 : Bryan Helmkamp [brynary.com](http://brynary.com) - $100 : Fusionary Media Inc. [fusionary.com](http://fusionary.com) - $200 : Wilson Bilkovich - $20 : Joel Hayhurst - $25 : Pawel Szymczykowski - $100 : Thomas Shelton - $65 : Assaf Arkin: labnotes/co.mments.com [co.mments.com](http://co.mments.com) - $20 : T Dean Strelau - $50 : rssfwd [rssfwd.com](http://rssfwd.com) - $20 : Dave Lehman - $50 : Tobias Luetke [leetsoft.com](http://leetsoft.com) - $25 : Luke Melia [www.lukemelia.com/devblog/](http://www.lukemelia.com/devblog/) - $20 : Andre Arko - $30 : Matrix9180.org [matrix9180.org](http://matrix9180.org) - $10 : Daniel Haran - $50 : Ajaya Agrawalla - $20 : William Groppe - $50 : Hammed Malik - $12 : Sebastien Goetz - $30 : Stephen Waits - $20 : Rodgers Estes - $25 : Speedy Mac LLC [speedymac.com](http://speedymac.com) - $20 : Michael Czepiel - $500 : Fingertips [www.fngtps.com](http://www.fngtps.com) - $15 : Matthew Turner - $50 : Emrys Holding B.V. - $250 : Darrin Wortlehock - $100 : YUUICHIROU MASUI - $20 : Laust Ladefoged - $64 : Rushed Sunlight [rushedsunlight.com](http://rushedsunlight.com) - $10 : Niko Dittmann - $20 : Justin Mecham (observationpoint.org) [observationpoint.org](http://observationpoint.org) - $5 : Damien Timewell - $500 : Lauri Jutila (reforge.fi) [reforge.fi](http://reforge.fi) - $10 : Pier-Hugues Pellerin - $20 : Stuart Johnson - $20 : Thomas Wright - $50 : Bryan Liles - $100 : Russell Tracey - $50 : Timothy Olsen - $50 : Axel Molina - $25 : Ibop - $20 : Sustainable Websites [sustainablewebsites.com](http://sustainablewebsites.com) - $100 : Sean Hussey - $73 : Jeremy Kleindl - $5000 : Derek Sivers/CD Baby [cdbaby.com](http://cdbaby.com) - $20 : Nicolas Paton - $50 : Thomas Kersten - $100 : Patrick Crowley/Mokolabs [mokolabs.com](http://mokolabs.com) - $50 : William Hamilton - $20 : David Rice [davidjrice.co.uk](http://davidjrice.co.uk) - $35 : Nathan Witmer - $100 : Jarkko Laine [jlaine.net](http://jlaine.net) - $100 : Michael Genereux - $20 : Scott Harper - $50 : Justin Palmer [encytemedia.com](http://encytemedia.com) - $50 : CM Gerungan - $20 : Magnus Hjelm - $25 : Damon Clinkscales [damonclinkscales.com](http://damonclinkscales.com) - $50 : Shift Media Group - $25 : Christi Balan [evil.che.lu](http://evil.che.lu) - $50 : Jonathan Younger - $20 : André Michael Bonkowski - $50 : Jordan Fowler - $30 : Will Mitchell - $100 : Collective Idea [collectiveidea.com](http://collectiveidea.com) - $50 : Jeff Ward, Animikii Inc. [animikii.com](http://animikii.com) - $20 : Michael Air - $20 : Ken Date - $50 : KENGO Nakajima - $75 : Scott Russell - $150 : inVisible GmbH [invisible.ch](http://invisible.ch) - $37 : Alain Ravet - $50 : Scott Bauer [railsaddict.com](http://railsaddict.com) - $10 : Matthew Parrish - $100 : Jim Greer - $40 : Robert Wayment - $10 : Todd Sayre - $20 : Doug [blog.straw-dogs.co.uk](http://blog.straw-dogs.co.uk) - $5 : Jeremy McAnally - $25 : Brian Anderson - $50 : Thomas Fuchs - $5 : Mathew Schaffer - $100 : Boboroshi & Hankins [meticulous.com](http://meticulous.com) - $50 : Tom Ward - $10 : Bruno Miranda [bopia.com](http://bopia.com) - $120 : Ryan Findley [neomind.com](http://neomind.com) - $75 : Alex Wolfe - $25 : Noah Stern - $20 : Stephen Caudill - $20 : Jason LaPier [tooshrewd.com](http://tooshrewd.com) - $20 : Nicholas Zadrozny - $10 : Leif Uwe Vogelsang - $20 : Coby Randquist - $30 : Steve Erickson - $34 : Brian Ford - $30 : Grant McInnes - $42 : Re-Cog Ltd - $100 : Needmore Designs, LLC - $25 : Seth Fitzsimmons - $100 : Near Time, Inc. - $100 : RailsForum.com [railsforum.com](http://railsforum.com) - $50 : Scott Mace - $20 : Dennis Sutch - $150 : Peter Styles - $20 : Daniel Von Fange - $250 : Paul Maritz - $20 : Justin Kay - $10 : Daniel Schierbeck - $20 : Gregory Spurrier - $30 : Artist Haus - $100 : Daisuke Yamazaki - $10 : S Burkhard - $2000 : FiveRuns [fiveruns.com](http://fiveruns.com)

Total: $16182

- Mean: $104 - Median: $50 - Number of donators: 156