reform 2.1.0 → 2.2.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 22e0b3849f8a705c51f5e805dfaca960279b8d3d
-  data.tar.gz: 1fa928b3309dcca60a1c5801a58acca34d7996ee
+  metadata.gz: 1b2a5be877cbaaa043ad0bfbcd2653da257699de
+  data.tar.gz: f1a4041fe62f7a7f5206953d587d7d4318464499
 SHA512:
-  metadata.gz: 5daaf2a361ee1a200b7d300f926ff6e4acf7503d73b5b3dcde106201d9b6bcf8a015ba4472ba5496a67af48af7be7bd4879d6afa6ed2cee649ec776ec437afea
-  data.tar.gz: 1adf91b4dfd4de9e14871b7f56953cd83ce765d6d1576858314ba4416f9c15c0d9eaad57b26b450345c8d4420ffd3ff524b67df210665d9f4268f4484a9b8894
+  metadata.gz: 97ef0aa8b71924a2500eebc80640621f0c54da292f438ded3ede85fd026f9f877008e99563253918157e221681e555c7144d65bf332c036c3a031bde526eaf07
+  data.tar.gz: 57b827c389e08eea790c146dfac6a1bc14f6e5f24e654d15aace5f7f07a674227ff5b9d4b1eb3051be15c99790e4937ffa05796aa4e56d223d7913087b8552e7

data/.gitignore

@@ -16,4 +16,3 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
-test/dummy/log/*.log

data/.travis.yml

@@ -1,19 +1,11 @@
 language: ruby
 rvm:
   - 2.2.3
-  - 1.9.3
-services:
-  - mongodb
+  - 2.0.0
 gemfile:
-  - gemfiles/Gemfile.rails-4.2
-  - gemfiles/Gemfile.rails-4.1
-  - gemfiles/Gemfile.rails-4.0
-  - gemfiles/Gemfile.rails-3.2
-  - gemfiles/Gemfile.rails-3.1
-  # - gemfiles/Gemfile.rails-3.0
+  - gemfiles/Gemfile.disposable-0.3
+
 matrix:
   fast_finish: true
-  allow_failures:
-    - rvm: 1.9.3
 before_install:
-  - gem install bundler
+  - gem install bundler

data/CHANGES.md

@@ -1,3 +1,11 @@
+## 2.2.0
+
+* Remove `reform/rails`. This is now handled via the `reform-rails` gem which you have to bundle.
+* For coercion, we now use [dry-types](https://github.com/dry-rb/dry-types) as a replacement for the deprecated virtus. You have to change to dry-types' constants, e.g. `type: Types::Form::Bool`.
+* Use disposable 0.3.0. This gives us the long-awaited `nilify: true` option.
+
+####### TODO: fix Module and coercion Types::*
+
 ## 2.1.0
 
 You should be able to upgrade from 2.0 without any code changes.

data/README.md

@@ -1,6 +1,7 @@
 # Reform
 
 [![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
+[![TRB Newsletter](https://img.shields.io/badge/TRB-newsletter-lightgrey.svg)](http://trailblazer.to/newsletter/)
 [![Build
 Status](https://travis-ci.org/apotonick/reform.svg)](https://travis-ci.org/apotonick/reform)
 [![Gem Version](https://badge.fury.io/rb/reform.svg)](http://badge.fury.io/rb/reform)
@@ -11,17 +12,13 @@ Reform gives you a form object with validations and nested setup of models. It i
 
 Although reform can be used in any Ruby framework, it comes with [Rails support](#rails-integration), works with [simple_form and other form gems](#formbuilder-support), allows nesting forms to implement [has_one](#nesting-forms-1-1-relations) and [has_many](#nesting-forms-1-n-relations) relationships, can [compose a form](#compositions) from multiple objects and gives you [coercion](#coercion).
 
-## This is not Reform 1.x!
+## Full Documentation
 
-Temporary note: This is the README and API for Reform 2. On the public API, only a few tiny things have changed. Here are the [Reform 1.2 docs](https://github.com/apotonick/reform/blob/v1.2.6/README.md).
+Reform is part of the [Trailblazer](http://trailblazer.to) framework. [Full documentation](http://trailblazer.to/gems/reform) is available on the project site.
 
-Anyway, please upgrade and _report problems_ and do not simply assume that we will magically find out what needs to get fixed. When in trouble, join us on [Gitter](https://gitter.im/trailblazer/chat).
+## Reform 2.2
 
-[Full documentation for Reform](http://trailblazer.to/gems/reform) is available online, or support us and grab the [Trailblazer book](https://leanpub.com/trailblazer). There is an [Upgrading Guide](http://trailblazer.to/gems/reform/upgrading-guide.html) to help you migrate from Reform 1.x.
-
-## Disposable
-
-Every form in Reform is a _twin_. Twins are non-persistent domain objects from the [Disposable gem](https://github.com/apotonick/disposable). All features of Disposable, like renaming fields, change tracking, etc. are available in Reform, too.
+Temporary note: Reform 2.2 does **not automatically load Rails files** anymore (e.g. `ActiveModel::Validations`). You need the `reform-rails` gem, see [Installation](#installation).
 
 ## Defining Forms
 
@@ -131,6 +128,16 @@ This will sync the data to the model and then call `album.save`.
 
 Sometimes, you need to do saving manually.
 
+## Default values
+
+Reform allows default values to be provided for properties.
+
+```ruby
+class AlbumForm < Reform::Form
+  property :price_in_cents, default: 9_95
+end
+```
+
 ## Saving Forms Manually
 
 Calling `#save` with a block will provide a nested hash of the form's properties and values. This does **not call `#save` on the models** and allows you to implement the saving yourself.
@@ -241,63 +248,29 @@ The block form of `#save` would give you the following data.
 The manual saving with block is not encouraged. You should rather check the Disposable docs to find out how to implement your manual tweak with the official API.
 
 
-## Populating Forms for Validation
-
-This topic is thorougly covered in the [Trailblazer book](https://leanpub.com/trailblazer) in chapters _Nested Forms_ and _Mastering Forms_.
+## Populating Forms
 
-With a complex nested setup it can sometimes be painful to setup the model object graph.
-
-Let's assume you rendered the following form.
-
-```ruby
-@form = AlbumForm.new(Album.new(songs: [Song.new, Song.new]))
-```
-
-This will render two nested forms to create new songs.
-
-In `validate`, you're supposed to setup the very same object graph, again. Reform has no way of remembering what the object setup was like a request ago.
-
-So, the following code will fail.
-
-```ruby
-@form = AlbumForm.new(Album.new).validate(params[:album])
-```
-
-However, you can advise Reform to setup the correct objects for you.
-
-```ruby
-class AlbumForm < Reform::Form
-  collection :songs, populate_if_empty: Song do
-    # ..
-  end
-```
+Very often, you need to give Reform some information how to create or find nested objects when `validate`ing. This directive is called _populator_ and [documented here](http://trailblazer.to/gems/reform/populator.html).
 
-This works for both `property` and `collection` and instantiates `Song` objects where they're missing when calling `#validate`.
+## Installation
 
-If you want to create the objects yourself, because you're smarter than Reform, do it with a lambda.
+Add this line to your Gemfile:
 
 ```ruby
-class AlbumForm < Reform::Form
-  collection :songs, populate_if_empty: lambda { |fragment, args| Song.new } do
-    # ..
-  end
+gem "reform"
 ```
 
-Reform also allows to completely override population using the `:populator` options. This is [documented here](http://trailblazer.to/gems/reform/populators.html), and also in the Trailblazer book.
-
-## Installation
+Reform works fine with Rails 3.1-5.0. However, inheritance of validations with `ActiveModel::Validations` is broken in Rails 3.2 and 4.0.
 
-Add this line to your Gemfile:
+Since Reform 2.2, you have to add the `reform-rails` gem to your `Gemfile` to automatically load ActiveModel/Rails files.
 
 ```ruby
-gem 'reform'
+gem "reform-rails"
 ```
 
-Reform works fine with Rails 3.1-4.2. However, inheritance of validations with `ActiveModel::Validations` is broken in Rails 3.2 and 4.0.
-
 Since Reform 2.0 you need to specify which **validation backend** you want to use (unless you're in a Rails environment where ActiveModel will be used).
 
-To use ActiveModel (not recommended as it doesn't support removing validations).
+To use ActiveModel (not recommended because very out-dated).
 
 ```ruby
 require "reform/form/active_model/validations"
@@ -306,12 +279,12 @@ Reform::Form.class_eval do
 end
 ```
 
-To use Lotus validations (recommended).
+To use dry-validation (recommended).
 
 ```ruby
-require "reform/form/lotus"
+require "reform/form/dry"
 Reform::Form.class_eval do
-  include Reform::Form::Lotus
+  feature Reform::Form::Dry
 end
 ```
 
@@ -338,708 +311,28 @@ When initializing a composition, you have to pass a hash that contains the compo
 AlbumForm.new(album: album, cd: CD.find(1))
 ```
 
-=> rendering
-=> sync with block
-
-## Hash Fields
+## More
 
-Reform can also handle deeply nested hash fields from serialized hash columns. This is [documented here](https://github.com/apotonick/disposable#struct).
-
-=> Example
+Reform comes many more optional features, like hash fields, coercion, virtual fields, and so on. Check the [full documentation here](http://trailblazer.to/gems/reform).
 
 <a href="https://leanpub.com/trailblazer">
-![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
+![](http://trailblazer.to/images/3dbuch-freigestellt.png)
 </a>
 
-Reform is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy my book](https://leanpub.com/trailblazer) to support the development and learn everything about Reform. Currently the book discusses:
-
-* Form objects, the DSL and basic API (chapter 2 and 3)
-* Basic validations and rendering forms (chapter 3)
-* Nested forms, prepopulating and validation populating and pre-selecting values (chapter 5)
-
-More chapters are coming!
-
-
-
-
-## Nomenclature
-
-Reform comes with two base classes.
-
-* `Form` is what made you come here - it gives you a form class to handle all validations, wrap models, allow rendering with Rails form helpers, simplifies saving of models, and more.
-* `Contract` gives you a sub-set of `Form`: [this class](#contracts) is meant for API validation where already populated models get validated without having to maintain validations in the model classes.
-
-
-
-Luckily, this can be shortened as follows.
-
-```ruby
-class SongForm < Reform::Form
-  property :title, validates: {presence: true}
-  property :length, validates: {numericality: true}
-end
-```
-
-Use `properties` to bulk-specify fields.
-
-```ruby
-class SongForm < Reform::Form
-  properties :title, :length, validates: {presence: true} # both required!
-  validates :length, numericality: true
-end
-```
-
-
-
-If the form wraps multiple models, via [composition](#compositions), you can access them like this:
-
-```ruby
-  @form.save do |nested|
-    song = @form.model[:song]
-    label = @form.model[:label]
-  end
-```
-
-Note that you can call `#sync` and _then_ call `#save { |hsh| }` to save models yourself.
-
-
-## Contracts
-
-Contracts give you a sub-set of the `Form` API.
-
-1. `#initialize` accepts an already populated model.
-2. `#validate` will run defined validations (without accepting a params hash as in `Form`).
-
-Contracts can be used to completely remove validation logic from your model classes. Validation should happen in a separate layer - a `Contract`.
-
-### Defining Contracts
-
-A contract looks like a form.
-
-```ruby
-class AlbumContract < Reform::Contract
-  property :title
-  validates :title, length: {minimum: 9}
-
-  collection :songs do
-    property :title
-    validates :title, presence: true
-  end
-```
-
-It defines the validations and the object graph to be inspected.
-
-In future versions and with the upcoming [Trailblazer framework](https://github.com/apotonick/trailblazer), contracts can be inherited from forms, representers, and cells, and vice-versa. Actually this already works with representer inheritance - let me know if you need help.
-
-### Using Contracts
-
-Applying a contract is simple, all you need is a populated object (e.g. an album after `#assign_attributes`).
-
-```ruby
-album.assign_attributes(..)
-
-contract = AlbumContract.new(album)
-
-if contract.validate
-  album.save
-else
-  raise contract.errors.messages.inspect
-end
-```
-
-Contracts help you to make your data layer a dumb persistance tier. My [upcoming book discusses that in detail](http://nicksda.apotomo.de).
-
-```
-
-This basically works like a nested `property` that iterates over a collection of songs.
-
-
-
-### Turning Off Autosave
-
-You can assign Reform to _not_ call `save` on a particular nested model (per default, it is called automatically on all nested models).
-
-```ruby
-class AlbumForm < Reform::Form
-  # ...
-
-  collection :songs, save: false do
-    # ..
-  end
-```
-
-The `:save` options set to false won't save models.
-
-
-
-
-
-## Compositions
-
-Sometimes you might want to embrace two (or more) unrelated objects with a single form. While you could write a simple delegating composition yourself, reform comes with it built-in.
-
-Say we were to edit a song and the label data the record was released from. Internally, this would imply working on the `songs` table and the `labels` table.
-
-```ruby
-class SongWithLabelForm < Reform::Form
-  include Composition
-
-  property :title, on: :song
-  property :city,  on: :label
-
-  model :song # only needed in ActiveModel context.
-
-  validates :title, :city, presence: true
-end
-```
-
-Note that reform needs to know about the owner objects of properties. You can do so by using the `on:` option.
-
-Also, the form needs to have a main object configured. This is where ActiveModel-methods like `#persisted?` or '#id' are delegated to. Use `::model` to define the main object.
-
-
-### Composition: Setup
-
-The constructor slightly differs.
-
-```ruby
-@form = SongWithLabelForm.new(song: Song.new, label: Label.new)
-```
-
-### Composition: Rendering
-
-After you configured your composition in the form, reform hides the fact that you're actually showing two different objects.
-
-```haml
-= form_for @form do |f|
-
-  Song:     = f.input :title
-
-  Label in: = f.input :city
-```
-
-### Composition: Processing
-
-When using `#save' without a block reform will use writer methods on the different objects to push validated data to the properties.
-
-Here's what the block parameters look like.
-
-```ruby
-@form.save do |nested|
-
-  nested #=> {
-         #   song:  {title: "Rio"}
-         #   label: {city: "London"}
-         #   }
-end
-```
-
-
-## Forms In Modules
-
-To maximize reusability, you can also define forms in modules and include them in other modules or classes.
-
-```ruby
-module SongsForm
-  include Reform::Form::Module
-
-  collection :songs do
-    property :title
-    validates :title, presence: true
-  end
-end
-```
-
-This can now be included into a real form.
-
-```ruby
-class AlbumForm < Reform::Form
-  property :title
-
-  include SongsForm
-end
-```
-
-Note that you can also override properties [using inheritance](#inheritance) in Reform.
-
-When using coercion, make sure the including form already contains the `Coercion` module.
-
-
-## Inheritance
-
-Forms can be derived from other forms and will inherit all properties and validations.
-
-```ruby
-class AlbumForm < Reform::Form
-  property :title
-
-  collection :songs do
-    property :title
-
-    validates :title, presence: true
-  end
-end
-```
-
-Now, a simple inheritance can add fields.
-
-```ruby
-class CompilationForm < AlbumForm
-  property :composers do
-    property :name
-  end
-end
-```
-
-This will _add_ `composers` to the existing fields.
-
-You can also partially override fields using `:inherit`.
-
-```ruby
-class CompilationForm < AlbumForm
-  property :songs, inherit: true do
-    property :band_id
-    validates :band_id, presence: true
-  end
-end
-```
-
-Using `inherit:` here will extend the existing `songs` form with the `band_id` field. Note that this simply uses [representable's inheritance mechanism](https://github.com/apotonick/representable/#partly-overriding-properties).
-
-## Coercion
-
-Often you want incoming form data to be converted to a type, like timestamps. Reform uses [virtus](https://github.com/solnic/virtus) for coercion, the DSL is seamlessly integrated into Reform with the `:type` option.
-
-### Virtus Coercion
-
-Be sure to add `virtus` to your Gemfile.
-
-```ruby
-require 'reform/form/coercion'
-
-class SongForm < Reform::Form
-  include Coercion
-
-  property :written_at, type: DateTime
-end
-
-form.validate("written_at" => "26 September")
-```
-
-Coercion only happens in `#validate`.
-
-```
-form.written_at #=> <DateTime "2014 September 26 00:00">
-```
-
-### Manual Coercing Values
-
-If you need to filter values manually, you can override the setter in the form.
-
-```ruby
-class SongForm < Reform::Form
-  property :title
-
-  def title=(value)
-    super sanitize(value) # value is raw form input.
-  end
-end
-```
-
-As with the built-in coercion, this setter is only called in `#validate`.
-
-
-## Virtual Attributes
-
-Virtual fields come in handy when there's no direct mapping to a model attribute or when you plan on displaying but not processing a value.
-
-
-### Virtual Fields
-
-Often, fields like `password_confirmation` should neither be read from nor written back to the model. Reform comes with the `:virtual` option to handle that case.
-
-```ruby
-class PasswordForm < Reform::Form
-  property :password
-  property :password_confirmation, virtual: true
-```
-
-Here, the model won't be queried for a `password_confirmation` field when creating and rendering the form. When saving the form, the input value is not written to the decorated model. It is only readable in validations and when saving the form manually.
-
-```ruby
-form.validate("password" => "123", "password_confirmation" => "321")
-
-form.password_confirmation #=> "321"
-```
-
-The nested hash in the block-`#save` provides the same value.
-
-```ruby
-form.save do |nested|
-  nested[:password_confirmation] #=> "321"
-```
-
-### Read-Only Fields
-
-When you want to show a value but skip processing it after submission the `:writeable` option is your friend.
-
-```ruby
-class ProfileForm < Reform::Form
-  property :country, writeable: false
-```
-
-This time reform will query the model for the value by calling `model.country`.
-
-You want to use this to display an initial value or to further process this field with JavaScript. However, after submission, the field is no longer considered: it won't be written to the model when saving.
-
-It is still readable in the nested hash and through the form itself.
-
-```ruby
-form.save do |nested|
-  nested[:country] #=> "Australia"
-```
-
-### Write-Only Fields
-
-A third alternative is to hide a field's value but write it to the database when syncing. This can be achieved using the `:readable` option.
-
-```ruby
-property :credit_card_number, readable: false
-```
-
-## Validations From Models
-
-Sometimes when you still keep validations in your models (which you shouldn't) copying them to a form might not feel right. In that case, you can let Reform automatically copy them.
-
-```ruby
-class SongForm < Reform::Form
-  property :title
-
-  extend ActiveModel::ModelValidations
-  copy_validations_from Song
-end
-```
-
-Note how `copy_validations_from` copies over the validations allowing you to stay DRY.
-
-This also works with Composition.
-
-```ruby
-class SongForm < Reform::Form
-  include Composition
-  # ...
-
-  extend ActiveModel::ModelValidations
-  copy_validations_from song: Song, band: Band
-end
-```
-
-Be warned that we _do not_ encourage copying validations. You should rather move validation code into forms and not work on your model directly anymore. Also, please note that the ```copy_validations_from``` line _must_ go below your property definitions for the validations to copy correctly.
-
-## Agnosticism: Mapping Data
-
-Reform doesn't really know whether it's working with a PORO, an `ActiveRecord` instance or a `Sequel` row.
-
-When rendering the form, reform calls readers on the decorated model to retrieve the field data (`Song#title`, `Song#length`).
-
-When syncing a submitted form, the same happens using writers. Reform simply calls `Song#title=(value)`. No knowledge is required about the underlying database layer.
-
-The same applies to saving: Reform will call `#save` on the main model and nested models.
-
-Nesting forms only requires readers for the nested properties as `Album#songs`.
-
-
-## Rails Integration
-
-Check out [@gogogarret](https://twitter.com/GoGoGarrett/)'s [sample Rails app](https://github.com/gogogarrett/reform_example) using Reform.
-
-Rails and Reform work together out-of-the-box.
-
-However, you should know about two things.
-
-1. In case you explicitely _don't_ want to have automatic support for `ActiveRecord` or `Mongoid` and form builder: `require reform/form`, only.
-2. In some setups around Rails 4 the `Form::ActiveRecord` module is not loaded properly, usually triggering a `NoMethodError` saying `undefined method 'model'`. If that happened to you, `require 'reform/rails'` manually at the bottom of your `config/application.rb`.
-3. Mongoid form gets loaded with the gem if `Mongoid` constant is defined.
-
-
-## ActiveRecord Compatibility
-
-Reform provides the following `ActiveRecord` specific features. They're mixed in automatically in a Rails/AR setup.
-
- * Uniqueness validations. Use `validates_uniqueness_of` in your form.
-
-As mentioned in the [Rails Integration](https://github.com/apotonick/reform#rails-integration) section some Rails 4 setups do not properly load.
-
-You may want to include the module manually then.
-
-```ruby
-class SongForm < Reform::Form
-  include Reform::Form::ActiveRecord
-```
-
-## Mongoid Compatibility
-
-Reform provides the following `Mongoid` specific features. They're mixed in automatically in a Rails/Mongoid setup.
-
- * Uniqueness validations. Use `validates_uniqueness_of` in your form.
-
-You may want to include the module manually then.
-
-```ruby
-class SongForm < Reform::Form
-  include Reform::Form::Mongoid
-```
-
-## Uniqueness Validation
-
-Both ActiveRecord and Mongoid modules will support "native" uniqueness support from the model class when you use `validates_uniqueness_of`. They will provide options like `:scope`, etc.
-
-You're encouraged to use Reform's non-writing `unique: true` validation, though. [Learn more](http://trailblazer.to/gems/reform/validation.html)
-
-## ActiveModel Compliance
-
-Forms in Reform can easily be made ActiveModel-compliant.
-
-Note that this step is _not_ necessary in a Rails environment.
-
-```ruby
-class SongForm < Reform::Form
-  include Reform::Form::ActiveModel
-end
-```
-
-If you're not happy with the `model_name` result, configure it manually via `::model`.
-
-```ruby
-class CoverSongForm < Reform::Form
-  include Reform::Form::ActiveModel
-
-  model :song
-end
-```
-
-`::model` will configure ActiveModel's naming logic. With `Composition`, this configures the main model of the form and should be called once.
-
-This is especially helpful when your framework tries to render `cover_song_path` although you want to go with `song_path`.
-
-
-## FormBuilder Support
-
-To make your forms work with all the form gems like `simple_form` or Rails `form_for` you need to include another module.
-
-Again, this step is implicit in Rails and you don't need to do it manually.
-
-```ruby
-class SongForm < Reform::Form
-  include Reform::Form::ActiveModel
-  include Reform::Form::ActiveModel::FormBuilderMethods
-end
-```
-
-### Simple Form
-
-If you want full support for `simple_form` do as follows.
-
-```ruby
-class SongForm < Reform::Form
-  include ActiveModel::ModelReflections
-```
-
-Including this module will add `#column_for_attribute` and other methods need by form builders to automatically guess the type of a property.
-
-## Validations For File Uploads
-
-In case you're processing uploaded files with your form using CarrierWave, Paperclip, Dragonfly or Paperdragon we recommend using the awesome [file_validators](https://github.com/musaffa/file_validators) gem for file type and size validations.
-
-```ruby
-class SongForm < Reform::Form
-  property :image
-
-  validates :image, file_size: {less_than: 2.megabytes},
-    file_content_type: {allow: ['image/jpeg', 'image/png', 'image/gif']}
-```
-
-## Multiparameter Dates
-
-Composed multi-parameter dates as created by the Rails date helper are processed automatically when `multi_params: true` is set for the date property and the `MultiParameterAttributes` feature is included. As soon as Reform detects an incoming `release_date(i1)` or the like it is gonna be converted into a date.
-
-```ruby
-class AlbumForm < Reform::Form
-  feature Reform::Form::ActiveModel::FormBuilderMethods
-  feature Reform::Form::MultiParameterAttributes
-
-  collection :songs do
-    feature Reform::Form::ActiveModel::FormBuilderMethods
-    property :title
-    property :release_date, :multi_params => true
-    validates :title, :presence => true
-  end
-end
-```
-
-Note that the date will be `nil` when one of the components (year/month/day) is missing.
+Reform is part of the [Trailblazer project](http://trailblazer.to). Please [buy my book](https://leanpub.com/trailblazer) to support the development and learn everything about Reform - there's two chapters dedicated to Reform!
 
 
-## Security
+## Security And Strong_parameters
 
 By explicitely defining the form layout using `::property` there is no more need for protecting from unwanted input. `strong_parameter` or `attr_accessible` become obsolete. Reform will simply ignore undefined incoming parameters.
 
+## This is not Reform 1.x!
 
-## Nesting Without Inline Representers
-
-When nesting form, you usually use a so-called inline form doing `property :song do .. end`.
-
-Sometimes you want to specify an explicit form rather than using an inline form. Use the `form:` option here.
-
-```ruby
-property :song, form: SongForm
-```
-
-The nested `SongForm` is a stand-alone form class you have to provide.
-
-
-## Default Values For Presentation
-
-In case you want to change a value for presentation or provide a default value, override the reader. This is only considered when the form is rendered (e.g. in `form_for`).
-
-```ruby
-class SongForm < Reform::Form
-  property :genre
-
-  def genre
-    super || 'Punkrock'
-  end
-end
-```
-
-This will now be used when rendering the view.
-
-```haml
-= f.input :genre # calls form.genre which provides default.
-```
-
-## Dirty Tracker
-
-Every form tracks changes in `#validate` and allows to check if a particular property value has changed using `#changed?`.
-
-```ruby
-form.title => "Button Up"
-
-form.validate("title" => "Just Kiddin'")
-form.changed?(:title) #=> true
-```
-
-When including `Sync::SkipUnchanged`, the form won't assign unchanged values anymore in `#sync`.
-
-
-## Deserializing and Population
-
-A form object is just a twin. In `validate`, a representer is used to deserialize the incoming hash and populate the form twin graph. This means, you can use any representer you like and process data like JSON or XML, too.
-
-Representers can be inferred from the contract automatically using `Disposable::Schema`. You may then extend your representer with hypermedia, etc. in order to render documents. Check out the Trailblazer book (chapter Hypermedia APIs) for a full explanation.
-
-You can even write your own deserializer code in case you dislike Representable.
-
-```ruby
-class AlbumForm < Reform::Form
-  # ..
-
-  def deserialize!(document)
-    hash = YAML.parse(document)
-
-    self.title  = hash[:title]
-    self.artist = Artist.new if hash[:artist]
-  end
-end
-```
-
-The decoupling of deserializer and form object is one of the main reasons I wrote Reform 2.
-
-
-## Undocumented Features
-
-_(Please don't read this section!)_
-
-### Skipping Properties when Validating
-
-In `#validate`, you can ignore properties now using `:skip_if` for deserialization.
-
-```ruby
-property :hit, skip_if: lambda { |fragment, *| fragment["title"].blank? }
-```
-
-This works for both properties and nested forms. The property will simply be ignored when deserializing, as if it had never been in the incoming hash/document.
-
-For nested properties you can use `:skip_if: :all_blank` as a macro to ignore a nested form if all values are blank.
-
-Note that this still runs validations for the property, though.
-
-### Prepopulating Forms
-
-Docs: http://trailblazer.to/gems/reform/prepopulator.html
-
-When rendering a new form for an empty object, nested forms won't show up. The [Trailblazer book, chapter 5](https://leanpub.com/trailblazer), discusses this in detail.
-
-You can use the `:prepopulator` option to configure how to populate a nested form (this also works for scalar properties).
-
-```ruby
-property :song, prepopulator: ->(options) { self.song = Song.new } do
-  # ..
-end
-```
-
-This option is only executed when being instructed to do so, using the `#prepopulate!` method.
-
-```ruby
-form.prepopulate!
-```
-
-You can also pass options to `#prepopulate`.
-
-Only do this for forms that are about to get rendered, though.
-
-Collections and partial collection population is covered in chapter 5.
-
-
-### Populator
-
-You can run your very own populator logic if you're keen (and you know what you're doing).
-
-```ruby
-class AlbumForm < Reform::Form
-  # ...
-
-  collection :songs, populator: lambda { |fragment, args| args.binding[:form].new(Song.find fragment[:id]) } do
-    # ..
-  end
-```
-
-### Property Inflections
-
-When rendering a form you might need to access the options you provided to `property`.
-
-```ruby
-property :title, type: String
-```
-
-You can do this using `#options_for`.
-
-```ruby
-form.options_for(:title) # => {:readable=>true, :coercion_type=>String}
-```
-
-Note that Reform renames some options (e.g. `:type` internally becomes `:coercion_type`). Those names are private API and might be changed without deprecation. You better test rendering logic in a unit test to make sure you're forward-compatible.
-
-## Support
-
-If you run into any trouble chat with us on irc.freenode.org#trailblazer.
-
-
-## Maintainers
+Temporary note: This is the README and API for Reform 2. On the public API, only a few tiny things have changed. Here are the [Reform 1.2 docs](https://github.com/apotonick/reform/blob/v1.2.6/README.md).
 
-[Nick Sutterer](https://github.com/apotonick)
-[Garrett Heinlen](https://github.com/gogogarrett)
+Anyway, please upgrade and _report problems_ and do not simply assume that we will magically find out what needs to get fixed. When in trouble, join us on [Gitter](https://gitter.im/trailblazer/chat).
 
+[Full documentation for Reform](http://trailblazer.to/gems/reform) is available online, or support us and grab the [Trailblazer book](https://leanpub.com/trailblazer). There is an [Upgrading Guide](http://trailblazer.to/gems/reform/upgrading-guide.html) to help you migrate from Reform 1.x.
 
 ### Attributions!!!