README.md in friendly_id-4.1.0.beta.1 vs README.md in friendly_id-5.0.0.alpha.1
- old
+ new
@@ -1,9 +1,20 @@
# FriendlyId
-[](https://travis-ci.org/norman/friendly_id)
+**VERSION NOTE**
+**Rails 4**:
+Master branch of this repository contains FriendlyId 5 which is compatible with Rails 4.
+This version is under active development and not yet fully stable.
+
+**Rails 3**:
+If you wish to use this gem with Rails 3.1 or 3.2 you need to use FriendlyId version 4, which is the current stable release.
+Please see [4.0-stable
+branch](https://github.com/FriendlyId/friendly_id/tree/4.0-stable).
+
+[](https://travis-ci.org/FriendlyId/friendly_id)
+
FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for
Ruby on Rails. It allows you to create pretty URLs and work with human-friendly
strings as if they were numeric ids for Active Record models.
Using FriendlyId, it's easy to make your application use URLs like:
@@ -16,78 +27,140 @@
## FriendlyId Features
FriendlyId offers many advanced features, including: slug history and
-versioning, i18n, Globalize support, scoped slugs, reserved words, and custom
-slug generators.
+versioning, i18n, scoped slugs, reserved words, and custom slug generators.
-FriendlyId is compatible with Active Record **3.0** and higher.
+Note: FriendlyId 5.0 is compatible with Active Record **4.0** and higher only.
+For Rails 3.x, please use FriendlyId 4.x.
-## Version 4.x
-FriendlyId 4.x introduces many changes incompatible with 3.x. If you're
-upgrading, please [read the
-docs](http://rubydoc.info/github/norman/friendly_id/master/file/WhatsNew.md) to see what's
-new.
+## Version 5.x
-## Docs
+As of version 5.0, FriendlyId uses semantic versioning. Therefore, as you might
+infer from the version number, FriendlyId 5.0 introduces changes incompatible
+with 4.x.
-The current docs can always be found
-[here](http://rubydoc.info/github/norman/friendly_id/master/frames).
+Here's a summary of the most important changes:
-The best place to start is with the
-[Guide](http://rubydoc.info/github/norman/friendly_id/master/file/Guide.rdoc),
-which compiles the top-level RDocs into one outlined document.
+* FriendlyId no longer overrides `find`. If you want to do friendly finds, you
+ must do `Model.friendly.find` rather than `Model.find`.
-You might also want to watch Ryan Bates's [Railscast on FriendlyId](http://railscasts.com/episodes/314-pretty-urls-with-friendlyid).
+* Version 5.0 offers a new "candidates" functionality which makes it easy to
+ set up a list of alternate slugs that can be used to uniquely distinguish
+ records, rather than appending a sequence. For example:
-## Rails Quickstart
+```ruby
+class Restaurant < ActiveRecord::Base
+ extend FriendlyId
+ friendly_id :slug_candidates, use: :slugged
- gem install friendly_id
+ # Try building a slug based on the following fields in
+ # increasing order of specificity.
+ def slug_candidates
+ [
+ :name,
+ [:name, :city],
+ [:name, :street, :city],
+ [:name, :street_number, :street, :city]
+ ]
+ end
+end
+```
- rails new my_app
+* Now that candidates have been added, FriendlyId no longer uses a numeric
+ sequence to differentiate conflicting slug, but rather a GUID. This makes the
+ codebase simpler and more reliable when running concurrently, at the expense
+ of uglier ids being generated when there are conflicts.
- cd my_app
+* The Globalize module has been removed and will be released as its own gem.
+ Note that it has not yet been developed.
- gem "friendly_id", "~> 4.0.1"
+* The default sequence separator is now `-` rather than `--`.
- rails generate scaffold user name:string slug:string
+* Slugs are no longer regenerated when a record is saved. If you want to regenerate
+ a slug, you must explicitly set the slug column to nil:
- # edit db/migrate/*_create_users.rb
- add_index :users, :slug, unique: true
+```ruby
+restaurant.friendly_id # joes-diner
+restaurant.name = "The Plaza Diner"
+restaurant.save!
+restaurant.friendly_id # joes-diner
+restaurant.slug = nil
+restaurant.save!
+restaurant.friendly_id # the-plaza-diner
+```
- rake db:migrate
+* Like Rails 4, FriendlyId now requires Ruby 1.9.3 or higher.
- # edit app/models/user.rb
- class User < ActiveRecord::Base
- extend FriendlyId
- friendly_id :name, use: :slugged
- end
+## Docs
- User.create! name: "Joe Schmoe"
+The current docs can always be found
+[here](http://rubydoc.info/github/FriendlyId/friendly_id/master/frames).
- rails server
+The best place to start is with the
+[Guide](http://rubydoc.info/github/FriendlyId/friendly_id/master/file/Guide.rdoc),
+which compiles the top-level RDocs into one outlined document.
- GET http://localhost:3000/users/joe-schmoe
+You might also want to watch Ryan Bates's [Railscast on FriendlyId](http://railscasts.com/episodes/314-pretty-urls-with-friendlyid),
+which is now somewhat outdated but still mostly relevant.
- # If you're adding FriendlyId to an existing app and need
- # to generate slugs for existing users, do this from the
- # console, runner, or add a Rake task:
- User.find_each(&:save)
+## Rails Quickstart
+```shell
+rails new my_app
+cd my_app
+```
+```ruby
+# Gemfile
+gem 'friendly_id', github: 'FriendlyId/friendly_id', branch: 'master' # Note: You MUST use 5.0.0 or greater for Rails 4.0+
+```
+```shell
+rails generate scaffold user name:string slug:string
+```
+```ruby
+# edit db/migrate/*_create_users.rb
+add_index :users, :slug, unique: true
+```
+```shell
+rake db:migrate
+```
+```ruby
+# edit app/models/user.rb
+class User < ActiveRecord::Base
+ extend FriendlyId
+ friendly_id :name, use: :slugged
+end
+User.create! name: "Joe Schmoe"
+
+# Change User.find to User.friendly.find in your controller
+User.friendly.find(params[:id])
+```
+```shell
+rails server
+
+GET http://localhost:3000/users/joe-schmoe
+```
+```ruby
+# If you're adding FriendlyId to an existing app and need
+# to generate slugs for existing users, do this from the
+# console, runner, or add a Rake task:
+User.find_each(&:save)
+```
+
## Benchmarks
The latest benchmarks for FriendlyId are maintained
[here](http://bit.ly/friendly-id-benchmarks).
## Bugs
Please report them on the [Github issue
-tracker](http://github.com/norman/friendly_id/issues) for this project.
+tracker](http://github.com/FriendlyId/friendly_id/issues) for this project.
If you have a bug to report, please include the following information:
* **Version information for FriendlyId, Rails and Ruby.**
* Full stack trace and error message (if you have them).
@@ -101,35 +174,18 @@
article](http://yourbugreportneedsmore.info/).
## Thanks and Credits
FriendlyId was originally created by Norman Clarke and Adrian Mugnolo, with
-significant help early in its life by Emilio Tagua. I'm deeply grateful for the
-generous contributions over the years from [many
-volunteers](https://github.com/norman/friendly_id/contributors).
+significant help early in its life by Emilio Tagua. It is now maintained by
+Norman Clarke and Philip Arndt.
-Part of the inspiration to rework FriendlyId came from Darcy Laycock's library
-[Slugged](https://github.com/Sutto/slugged), which he was inspired to create
-because of frustrations he experienced while using FriendlyId 3.x. Seeing a
-smart programmer become frustrated with my code was enough of a kick in the
-butt to make me want to significantly improve this library.
+We're deeply grateful for the generous contributions over the years from [many
+volunteers](https://github.com/FriendlyId/friendly_id/contributors).
-Many thanks to him for providing valid, real criticism while still being a cool
-about it. I definitely recommend you check out his library if for some reason
-FriendlyId doesn't do it for you.
-
-Thanks also to Loren Segal and Nick Plante for YARD and the
-[rubydoc.info](http://rubydoc.info/) website which FriendlyId uses for
-documentation.
-
-Lastly, FriendlyId uses [Travis](http://travis-ci.org/) for continuous
-integration. It's an excellent, free service created by a whole bunch of [good
-people](https://github.com/travis-ci) - if you're not already using it, you
-should be!
-
## License
-Copyright (c) 2008-2012 Norman Clarke and contributors, released under the MIT
+Copyright (c) 2008-2013 Norman Clarke and contributors, released under the MIT
license.
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to