From 9d7560e205d32a7cbda3de8c32ca42e0312f62c3 Mon Sep 17 00:00:00 2001
From: Carl Lerche <carllerche@mac.com>
Date: Tue, 22 Jul 2008 21:34:06 -0700
Subject: [PATCH] Tweaked the SPECS document and added a rough outline for the
 new spec organization

---
 SPECS                             | 14 ++++++++--
 spec/integration/resource_spec.rb | 44 ++++++++++++++-----------------
 2 files changed, 32 insertions(+), 26 deletions(-)

diff --git a/SPECS b/SPECS
index b09a6f1f..a130b008 100644
--- a/SPECS
+++ b/SPECS
@@ -16,7 +16,7 @@ Writing Specs
   * Use existing models that are part of a metaphor.
   * Nest describe blocks (2 or 3 levels deep is probably fine).
   * Limit a describe block to 10 - 15 examples.
-  * Group specs by method being tested.
+  * Group specs by method being tested. (See the 'Ordering Specs' section)
   * Use custom matchers.
   
   = DON'T:
@@ -50,4 +50,14 @@ Mocks and Stubs
 
   Obviously, mocks and stubs are a powerful feature when it comes to BDD;
   however, remember that you are writing specs for behavior and NOT
-  implementation.
\ No newline at end of file
+  implementation.
+  
+Ordering Specs
+==============
+
+  Specs aren't much use if nobody can find where anything is, so keeping specs
+  well organized is critical. Currently, we are trying out the following
+  structure:
+  
+    * List guidelines here...
+  
\ No newline at end of file
diff --git a/spec/integration/resource_spec.rb b/spec/integration/resource_spec.rb
index 3f49501d..c01991f7 100644
--- a/spec/integration/resource_spec.rb
+++ b/spec/integration/resource_spec.rb
@@ -1,5 +1,10 @@
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
 
+# ------------------------------------------------------------
+# -----   Read SPECS for information about how to read   -----
+# -----   and contribute to the DataMapper specs.        -----
+# ------------------------------------------------------------
+
 if ADAPTER
   describe "DataMapper::Resource with #{ADAPTER}" do
     
@@ -15,8 +20,6 @@
     it "should be able to destroy objects" do
       lambda { @zoo.destroy.should be_true }.should_not raise_error
     end
-    
-  # --------------- ATTRIBUTE METHODS ---------------
 
     describe '#attribute_get' do
       it 'should provide #attribute_get' do
@@ -45,14 +48,6 @@
       end
     end
     
-    describe '#id' do
-      it "should be awesome"
-    end
-    
-    describe '#key' do
-      it "should be awesome"
-    end
-    
     describe '#eql?' do
       it "should return true if the objects are the same instances"
       it "should return false if the other object is not an instance of the same model"
@@ -62,7 +57,21 @@
       it "should return false if any of the properties are different"
     end
     
-  # --------------- REPOSITORY WRITE METHODS ---------------
+    describe '#id' do
+      it "should be awesome"
+    end
+    
+    describe '#inspect' do
+      it "should return a string representing the object"
+    end
+    
+    describe '#key' do
+      it "should be awesome"
+    end
+    
+    describe '#pretty_print' do
+      it "should display a pretty version of inspect"
+    end
 
     describe '#save' do
 
@@ -78,23 +87,10 @@
 
     end
     
-  # --------------- REPOSITORY METHODS ---------------
-    
     describe '#repository' do
       it "should return the repository associated with the object if there is one"
       it "should return the repository associated with the model if the object doesn't have one"
     end
-    
-  # -------------- MISCELLANEOUS METHODS ---------------
-    
-    describe '#inspect' do
-      it "should return a string representing the object"
-    end
-    
-    describe '#pretty_print' do
-      it "should display a pretty version of inspect"
-    end
-    
   end
 end