Add a Common Pitfalls section to the docs

Author: dkubb

docs/index.md

@@ -33,6 +33,8 @@ created_at: Fri Nov 30 15:29:01 +1030 2007
   <dd>Paranoia, Timezone Handling, Single Table Inheritance, and Multiple Repositories.</dd>
   <dt><a href="/docs/legacy.html">Working with Legacy Schemas</a></dt>
   <dd>Adapting data-store naming conventions to your own property names.</dd>
+  <dt><a href="/docs/pitfalls.html">Common Pitfalls</a></dt>
+  <dd>Solutions and work-arounds to common problems.</dd>
   <dt><a href="/docs/dm_more/">More</a></dt>
   <dd>Plugins galore for DataMapper.</dd>
 </dl>

docs/pitfalls.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Commom Pitfalls
+body_id: docs
+created_at: Sun Apr 01 21:13:13 -0700 2012
+---
+
+{{ page.title }}
+================
+
+Below is a list of common problems that someone new to DataMapper will
+encounter, along with work-arounds or solutions if possible.
+
+Implicit String property length
+-------------------------------
+
+When declaring a String property, DataMapper will add an implicit length of 50
+characters if nothing is explicitly declared.
+
+For example, the two class declarations have identical behaviour:
+
+{% highlight ruby linenos %}
+# with an implicit length
+class Post
+  include DataMapper::Resource
+
+  property :title, String
+end
+{% endhighlight %}
+
+{% highlight ruby linenos %}
+# with an explicit length
+class Post
+  include DataMapper::Resource
+
+  property :title, String, :length => 50
+end
+{% endhighlight %}
+
+The reason for this default is that DataMapper needs to know the underlying
+column constraints in order to add validations from the property definitions.
+Databases will often choose their own arbitrary length constraints if one is not
+declared (often 255 chars). We choose something a bit more restricted as a
+default because we wanted to encourage peolpe to declare it explicitly in their
+model, rather than relying on DM or the DB choosing an implicit limit.