Fixed #8918 -- Made FileField.upload_to optional.

Thanks leahculver for the suggestion and dc and vajrasky for work
on the patch.

3 files changed, 18 insertions, 13 deletions

diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt
index be3839e08f..ecc473762f 100644
--- a/docs/faq/usage.txt
+++ b/docs/faq/usage.txt
@@ -45,10 +45,9 @@ Using a :class:`~django.db.models.FileField` or an
    account.
 
 #. Add the :class:`~django.db.models.FileField` or
-   :class:`~django.db.models.ImageField` to your model, making sure to
-   define the :attr:`~django.db.models.FileField.upload_to` option to tell
-   Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload
-   files.
+   :class:`~django.db.models.ImageField` to your model, defining the
+   :attr:`~django.db.models.FileField.upload_to` option to specify a
+   subdirectory of :setting:`MEDIA_ROOT` to use for uploaded files.
 
 #. All that will be stored in your database is a path to the file
    (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index bcadf4d27a..0a3abae644 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -542,7 +542,7 @@ A :class:`CharField` that checks that the value is a valid email address.
 ``FileField``
 -------------
 
-.. class:: FileField(upload_to=None, [max_length=100, **options])
+.. class:: FileField([upload_to=None, max_length=100, **options])
 
 A file-upload field.
 
@@ -550,10 +550,14 @@ A file-upload field.
     The ``primary_key`` and ``unique`` arguments are not supported, and will
     raise a ``TypeError`` if used.
 
-Has one **required** argument:
+Has two optional arguments:
 
 .. attribute:: FileField.upload_to
 
+    .. versionchanged:: 1.7
+
+        ``upload_to`` was required in older versions of Django.
+
     A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
     setting to determine the value of the
     :attr:`~django.db.models.fields.files.FieldFile.url` attribute.
@@ -586,11 +590,9 @@ Has one **required** argument:
                             when determining the final destination path.
     ======================  ===============================================
 
-Also has one optional argument:
-
 .. attribute:: FileField.storage
 
-    Optional. A storage object, which handles the storage and retrieval of your
+    A storage object, which handles the storage and retrieval of your
     files. See :doc:`/topics/files` for details on how to provide this object.
 
 The default form widget for this field is a :class:`~django.forms.FileInput`.
@@ -604,9 +606,9 @@ takes a few steps:
    :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
    that this directory is writable by the Web server's user account.
 
-2. Add the :class:`FileField` or :class:`ImageField` to your model, making
-   sure to define the :attr:`~FileField.upload_to` option to tell Django
-   to which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
+2. Add the :class:`FileField` or :class:`ImageField` to your model, defining
+   the :attr:`~FileField.upload_to` option to specify a subdirectory of
+   :setting:`MEDIA_ROOT` to use for uploaded files.
 
 3. All that will be stored in your database is a path to the file
    (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
@@ -807,7 +809,7 @@ The default form widget for this field is a :class:`~django.forms.TextInput`.
 ``ImageField``
 --------------
 
-.. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options])
+.. class:: ImageField([upload_to=None, height_field=None, width_field=None, max_length=100, **options])
 
 Inherits all attributes and methods from :class:`FileField`, but also
 validates that the uploaded object is a valid image.
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 0f1a5de073..8fbd82adc6 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -246,6 +246,10 @@ File Uploads
   the file system permissions of directories created during file upload, like
   :setting:`FILE_UPLOAD_PERMISSIONS` does for the files themselves.
 
+* The :attr:`FileField.upload_to <django.db.models.FileField.upload_to>`
+  attribute is now optional. If it is omitted or given ``None`` or an empty
+  string, a subdirectory won't be used for storing the uploaded files.
+
 Forms
 ^^^^^