Add an upgrade guide for cqlengine

docs/cqlengine/upgrade_guide.rst

@@ -0,0 +1,136 @@
+========================
+Upgrade Guide
+========================
+
+This is an overview of things that changed as the cqlengine project was merged into
+cassandra-driver. While efforts were taken to preserve the API and most functionality exactly,
+conversion to this package will still require certain minimal updates (namely, imports).
+
+**THERE IS ONE FUNCTIONAL CHANGE**, described in the first section below.
+
+Functional Change
+=================
+Legacy cqlengine included a workaround for a Cassandra bug in which prepended list segments were
+reversed (`CASSANDRA-8733 <https://issues.apache.org/jira/browse/CASSANDRA-8733>`_). As of
+this integration, this workaround is removed. The first released integrated version emits
+a warning when prepend is used. Subsequent versions will have this warning removed.
+
+Remove cqlengine
+================
+To avoid confusion or mistakes using the legacy package in your application, it
+is prudent to remove the cqlengine package when upgrading to the integrated version.
+
+The driver setup script will warn if the legacy package is detected during install,
+but it will not prevent side-by-side installation.
+
+Organization
+============
+Imports
+-------
+cqlengine is now integrated as a sub-package of the driver base package 'cassandra'.
+Upgrading will require adjusting imports to cqlengine. For example::
+
+    from cqlengine import columns
+
+is now::
+
+    from cassandra.cqlengine import columns
+
+Package-Level Aliases
+---------------------
+Legacy cqlengine defined a number of aliases at the package level, which became redundant
+when the package was integrated for a driver. These have been removed in favor of absolute
+imports, and referring to cannonical definitions. For example, ``cqlengine.ONE`` was an alias
+of ``cassandra.ConsistencyLevel.ONE``. In the integrated package, only the 
+:class:`cassandra.ConsistencyLevel` remains.
+
+Additionally, submodule aliases are removed from cqlengine in favor of absolute imports.
+
+These aliases are removed, and not deprecated because they should be straightforward to iron out
+at module load time.
+
+Exceptions
+----------
+The legacy cqlengine.exceptions module had a number of Exception classes that were variously
+common to the package, or only used in specific modules. Common exceptions were relocated to
+cqlengine, and specialized exceptions were placed in the module that raises them. Below is a
+listing of updated locations:
+
+============================  ==========
+Exception class               New module
+============================  ==========
+CQLEngineException            cassandra.cqlengine
+ModelException                cassandra.cqlengine.models
+ValidationError               cassandra.cqlengine
+UndefinedKeyspaceException    cassandra.cqlengine.connection
+LWTException                  cassandra.cqlengine.query
+IfNotExistsWithCounterColumn  cassandra.cqlengine.query
+============================  ==========
+
+UnicodeMixin Consolidation
+--------------------------
+``class UnicodeMixin`` was defined in several cqlengine modules. This has been consolidated
+to a single definition in the cqlengine package init file. This is not technically part of 
+the API, but noted here for completeness.
+
+API Deprecations
+================
+This upgrade served as a good juncture to deprecate certain API features and invite users to upgrade
+to new ones. The first released version does not change functionality -- only introduces deprecation
+warnings. Future releases will remove these features in favor of the alternatives.
+
+Schema Management
+-----------------
+``cassandra.cqlengine.management.create_keyspace`` is deprecated. Instead, use the new replication-strategy-specific
+functions that accept explicit options for known strategies:
+
+- :func:`~.create_keyspace_simple`
+- :func:`~.create_keyspace_network_topology`
+
+``cassandra.cqlengine.management.delete_keyspace`` is deprecated in favor of a new function, :func:`~.drop_keyspace`. The
+intent is simply to make the function match the CQL verb it invokes.
+
+Model Inheritance
+-----------------
+The names for class attributes controlling model inheritance are changing. Changes are as follows:
+
+- Replace 'polymorphic_key' in the base class Column definition with :attr:`~.discriminator_column`
+- Replace the '__polymporphic_key__' class attribute the derived classes with :attr:`~.__discriminator_value__`
+
+The functionality is unchanged -- the intent here is to make the names and language around these attributes more precise. 
+For now, the old names are just deprecated, and the mapper will emit warnings if they are used. The old names
+will be removed in a future version.
+
+The example below shows a simple translation:
+
+Before::
+
+    class Pet(Model):
+        __table_name__ = 'pet'
+        owner_id = UUID(primary_key=True)
+        pet_id = UUID(primary_key=True)
+        pet_type = Text(polymorphic_key=True)
+        name = Text()
+
+    class Cat(Pet):
+        __polymorphic_key__ = 'cat'
+
+    class Dog(Pet):
+        __polymorphic_key__ = 'dog'
+        
+After::
+
+    class Pet(models.Model):
+        __table_name__ = 'pet'
+        owner_id = UUID(primary_key=True)
+        pet_id = UUID(primary_key=True)
+        pet_type = Text(discriminator_column=True)
+        name = Text()
+
+    class Cat(Pet):
+        __discriminator_value__ = 'cat'
+
+    class Dog(Pet):
+        __discriminator_value__ = 'dog'
+
+

docs/object_mapper.rst

@@ -7,6 +7,9 @@ cqlengine is the Cassandra CQL 3 Object Mapper packaged with this driver
 
 Contents
 --------
+:doc:`cqlengine/upgrade_guide`
+    For migrating projects from legacy cqlengine, to the integrated product
+
 :doc:`cqlengine/models`
     Examples defining models, and mapping them to tables
 
@@ -27,6 +30,7 @@ Contents
 .. toctree::
     :hidden:
 
+    cqlengine/upgrade_guide
     cqlengine/models
     cqlengine/queryset
     cqlengine/batches