From 78ad0a61a945684e1acf11111cec971d2dfa30c3 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Thu, 3 Dec 2009 14:58:58 +0000
Subject: [PATCH] Expanded on the SMTPConnection deprecation notes, and made
 the deprecation a PendingDeprecationWarning as per the deprecation
 guidelines.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11790 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 django/core/mail/__init__.py |  2 +-
 docs/releases/1.2.txt        | 38 +++++++++++++++++++++++++++++++++---
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/django/core/mail/__init__.py b/django/core/mail/__init__.py
index b02575793d..9a629035cf 100644
--- a/django/core/mail/__init__.py
+++ b/django/core/mail/__init__.py
@@ -105,6 +105,6 @@ class SMTPConnection(_SMTPConnection):
         import warnings
         warnings.warn(
             'mail.SMTPConnection is deprecated; use mail.get_connection() instead.',
-            DeprecationWarning
+            PendingDeprecationWarning
         )
         super(SMTPConnection, self).__init__(*args, **kwds)
diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt
index 24b43acd38..122b2f4927 100644
--- a/docs/releases/1.2.txt
+++ b/docs/releases/1.2.txt
@@ -42,8 +42,8 @@ changes that developers must be aware of:
  * All of the CSRF has moved from contrib to core (with backwards compatible
    imports in the old locations, which are deprecated).
 
-LazyObject
-----------
+``LazyObject``
+--------------
 
 ``LazyObject`` is an undocumented utility class used for lazily wrapping other
 objects of unknown type.  In Django 1.1 and earlier, it handled introspection in
@@ -67,6 +67,7 @@ changes:
 
        __members__ = property(lambda self: self.__dir__())
 
+
 .. _deprecated-features-1.2:
 
 Features deprecated in 1.2
@@ -88,7 +89,38 @@ deprecated, as described in the :ref:`upgrading notes <ref-csrf-upgrading-notes>
 ``SMTPConnection``
 ------------------
 
-This class has been deprecated in favor of the new generic e-mail backends.
+The ``SMTPConnection`` class has been deprecated in favor of a generic
+E-mail backend API. Old code that explicitly instantiated an instance
+of an SMTPConnection::
+
+    from django.core.mail import SMTPConnection
+    connection = SMTPConnection()
+    messages = get_notification_email()
+    connection.send_messages(messages)
+
+should now call :meth:`~django.core.mail.get_connection()` to
+instantiate a generic e-mail connection::
+
+    from django.core.mail import get_connection
+    connection = get_connection()
+    messages = get_notification_email()
+    connection.send_messages(messages)
+
+Depending on the value of the :setting:`EMAIL_BACKEND` setting, this
+may not return an SMTP connection. If you explicitly require an SMTP
+connection with which to send e-mail, you can explicitly request an
+SMTP connection::
+
+    from django.core.mail import get_connection
+    connection = get_connection('django.core.mail.backends.smtp')
+    messages = get_notification_email()
+    connection.send_messages(messages)
+
+If your call to construct an instance of ``SMTPConnection`` required
+additional arguments, those arguments can be passed to the
+:meth:`~django.core.mail.get_connection()` call::
+
+    connection = get_connection('django.core.mail.backends.smtp', hostname='localhost', port=1234)
 
 What's new in Django 1.2
 ========================