<commit_before>h1. Clearance

Rails authentication with email & password.

"We have clearance, Clarence.":http://www.youtube.com/v/mNRXJEE3Nz8

h2. Engine

Clearance is a Rails engine. It works with versions of Rails greater than 2.3.

h2. Wiki

Most information regarding Clearance is on the "Github Wiki":http://wiki.github.com/thoughtbot/clearance.

h2. Integration with Suspenders

Clearance is based on the same conventions and tools as "Suspenders":http://github.com/thoughtbot/suspenders If you use it, you already have some configuration mentioned below.

h2. Gem installation

In config/environment.rb:

    config.gem "thoughtbot-clearance", 
      :lib     => 'clearance', 
      :source  => 'http://gems.github.com', 
      :version => '0.6.1'

In config/environments/test.rb:

    config.gem 'thoughtbot-shoulda',
      :lib     => 'shoulda',
      :source  => "http://gems.github.com", 
      :version => '2.10.1'
    config.gem 'thoughtbot-factory_girl',
      :lib     => 'factory_girl',
      :source  => "http://gems.github.com", 
      :version => '1.2.1'

Then:

    rake gems:install
    rake gems:unpack
    rake gems:install RAILS_ENV=test
    rake gems:unpack  RAILS_ENV=test

h2. The generator

Make sure the development database exists and run the generator:

    script/generate clearance

A number of files will be created and instructions will be printed.

You may already have some of these files. Don't worry. You'll be asked if you want to overwrite them.

h2. Features

If you are using Cucumber on your application Clearance comes with a feature generator:

    script/generate clearance_features

All of the files generated should be new with the exception of the features/support/paths.rb file.  If you have not modified your paths.rb then you will be okay to replace it with this one.  If you need to keep your paths.rb file then you will need to add these locations in your paths.rb manually:

    def path_to(page_name)
      case page_name
       ...
      when /the sign up page/i
       new_user_path
      when /the sign in page/i
       new_session_path 
      when /the password reset request page/i
       new_password_path
      ...
    end

h2. Authors

Clearance was extracted out of "Hoptoad":http://hoptoadapp.com. We merged the authentication code from two of thoughtbot's client's Rails apps. The following people have made significant contributions, suggestions, and generally improved the library. Thank you!

<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, & <NAME>.

h2. Questions?

* Ask the "mailing list":http://groups.google.com/group/thoughtbot-clearance

h2. Bugs?

* Open up a "Lighthouse ticket":https://thoughtbot.lighthouseapp.com/projects/18503-clearance
<commit_msg>updating README for Rails engine instructions<commit_after>h1. Clearance

Rails authentication with email & password.

"We have clearance, Clarence.":http://www.youtube.com/v/mNRXJEE3Nz8

h2. Wiki

Most information regarding Clearance is on the "Github Wiki":http://wiki.github.com/thoughtbot/clearance.

h2. Engine

Clearance is a Rails engine. It works with versions of Rails greater than 2.3.

In config/environment.rb:

    config.gem "thoughtbot-clearance", 
      :lib     => 'clearance', 
      :source  => 'http://gems.github.com', 
      :version => '0.6.1'

Vendor the gem:

    rake gems:install
    rake gems:unpack

Make sure the development database exists and run the generator:

    script/generate clearance

A number of files will be created and instructions will be printed.

You may already have some of these files. Don't worry. You'll be asked if you want to overwrite them.

h2. Features

As your app evolves, you want to know that authentication still works. Clearance's opinion is that you should test its integration with your app using "Cucumber":http://cukes.info/.

In config/environments/test.rb:

    config.gem 'webrat',
      :version => '= 0.4.4'
    config.gem 'nokogiri',
      :version => '= 1.2.3'
    config.gem 'cucumber',
      :version => '= 0.3.0'
    config.gem 'thoughtbot-factory_girl',
      :lib     => 'factory_girl',
      :source  => "http://gems.github.com", 
      :version => '1.2.1'

Vendor the gems:

    rake gems:install RAILS_ENV=test
    rake gems:unpack  RAILS_ENV=test

Run the Cucumber generator (if you haven't already) and Clearance's feature generator:

    script/generate cucumber
    script/generate clearance_features

All of the files generated should be new with the exception of the features/support/paths.rb file. If you have not modified your paths.rb then you will be okay to replace it with this one. If you need to keep your paths.rb file then add these locations in your paths.rb manually:

    def path_to(page_name)
      case page_name
       ...
      when /the sign up page/i
       new_user_path
      when /the sign in page/i
       new_session_path 
      when /the password reset request page/i
       new_password_path
      ...
    end

h2. Integration with Suspenders

Clearance is based on the same conventions and tools as "Suspenders":http://github.com/thoughtbot/suspenders If you use it, you already have some configuration.

h2. Authors

Clearance was extracted out of "Hoptoad":http://hoptoadapp.com. We merged the authentication code from two of thoughtbot's client's Rails apps. The following people have made significant contributions, suggestions, and generally improved the library. Thank you!

<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, & <NAME>.

h2. Questions?

* Ask the "mailing list":http://groups.google.com/group/thoughtbot-clearance

h2. Bugs?

* Open up a "Lighthouse ticket":https://thoughtbot.lighthouseapp.com/projects/18503-clearance

{'fraction_non_alphanumeric': 0.0970187833879028, 'fraction_numerical': 0.010511804239186628, 'mean_word_length': 3.347565543071161, 'pattern_counts': {'":': 13, '<': 31, '<?xml version=': 0, '>': 49, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6763090', 'n_tokens_mistral': 1821, 'n_tokens_neox': 1704, 'n_words': 646}