2 files changed, 12 insertions, 3 deletions
diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index c6423e7a0..0f5518045 100644
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -100,8 +100,11 @@ Configuring Relationships
 =========================
 
 Relationships to other classes are done in the usual way, with the added
-feature that the class specified to :func:`~sqlalchemy.orm.relationship()`
-may be a string name.  The "class registry" associated with ``Base``
+feature that the class specified to :func:`~sqlalchemy.orm.relationship`
+may be a string name (note that :func:`~sqlalchemy.orm.relationship` is 
+only available as of SQLAlchemy 0.6beta2, and in all prior versions is known
+as :func:`~sqlalchemy.orm.relation`, 
+including 0.5 and 0.4).  The "class registry" associated with ``Base``
 is used at mapper compilation time to resolve the name into the actual
 class object, which is expected to have been defined once the mapper
 configuration is used:: 
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 26cb071b7..3337287d8 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -175,7 +175,13 @@ def create_session(bind=None, **kwargs):
 
 def relationship(argument, secondary=None, **kwargs):
     """Provide a relationship of a primary Mapper to a secondary Mapper.
-
+    
+    .. note:: This function is known as :func:`relation` in all versions
+      of SQLAlchemy prior to version 0.6beta2, including the 0.5 and 0.4 series.
+      :func:`~sqlalchemy.orm.relationship()` is only available starting with 
+      SQLAlchemy 0.6beta2.  The :func:`relation` name will remain available for 
+      the foreseeable future in order to enable cross-compatibility.
+    
     This corresponds to a parent-child or associative table relationship.  The
     constructed class is an instance of :class:`RelationshipProperty`.