Paperclip is Going Three-Point-Oh Nelly

The new version of your favorite file upload library, Paperclip3.0.0, has been released earlier today. We changed a lot of
internals to make Paperclip better. These changes lay the groundwork for the
shiny, new features that will come in the future.

Ruby 1.8.7 and Ruby on Rails 2.3.x are both reaching
end of life now, so this is a good time to drop support for them. This let us
remove some code and introduce a new validator syntax (below.)

If you’re still using Ruby on Rails 2.3.x or Ruby 1.8.7, you should lock
Paperclip to version 2.x by doing this:

gem "paperclip", "~> 2.7"

In some rare case that there’s a critical bug in Paperclip 2.7.x, we’ll release
a patch version under that minor version. However, you’re advised to upgrade to
a newer version of Ruby and Rails as soon as you can.

We’re working to extract functionality into modules. We’re not done with this
yet, and it is an ongoing process. If you’ve freedom patched
Paperclip, you’ll need to look out for this as some of the methods might have
new names or locations.

If you are developing a plugin for Paperclip—e.g. custom storage, a
processor, or a validator—we would love to hear from you. We want to
expose hooks to help you develop your plugin and reduce the risk of breaking
things in the future.

When you’re installing the new version of Paperclip, you’ll be greeted with this
upgrading message:

##################################################
# NOTE FOR UPGRADING FROM PRE-3.0 VERSION #
##################################################
Paperclip 3.0 introduces a non-backward compatible change in your attachment
path. This will help to prevent attachment name clashes when you have
multiple attachments with the same name. If you didn't alter your
attachment's path and are using Paperclip's default, you'll have to add
`:path` and `:url` to your `has_attached_file` definition. For example:
has_attached_file :avatar,
:path => ":rails_root/public/system/:attachment/:id/:style/:filename",
:url => "/system/:attachment/:id/:style/:filename"

Going forward, the default URL for your attachment will be
/system/:class/:attachment/:id_partition/:style/:filename. This will prevent
filename collisions and will reduce the number of files in a single directory.

All of the validators have been rewritten to take the full advantage of Rails 3.
They’re now in their own Validator class, and can be passed into validates or
validates_with like any other Active Model validator:

We are also introducing a validates_attachment method. This method is almost
the same as the validates method except you can skip the :attachment_
prefix. We’ve found this helpful when defining multiple validators on a single
attachment:

I would like to thank our contributors and all of the other
users who are helping to make Paperclip better and better. Please give this new
version a try. If you find a bug, please file an issue, or better, you
can also help us fixing it.

We’re thrilled to introduce the new Paperclip, and we hope that you’ll like them.