Update docs for on_delete requirement in Filer fields for Django 5.1

README.rst

@@ -49,26 +49,6 @@ Documentation
 Please head over to the separate `documentation <https://django-filer.readthedocs.io/en/latest/index.html>`_
 for all the details on how to install, configure and use django-filer.
 
-Upgrading
-=========
-
-Version 3.3
------------
-
-django-filer version 3 contains a change in security policy for file uploads.
-**By default, binary file or files of unknown type are not allowed to be uploaded.**
-To allow upload of binary files in your project, add
-
-.. code-block:: python
-
-    FILER_REMOVE_FILE_VALIDATORS = [
-        "application/octet-stream",
-    ]
-
-to your project's settings. Be aware that binary files always are a security risk.
-See the documentation for more information on how to configure file upload validators,
-e.g., running files through a virus checker.
-
 
 .. |pypi| image:: https://badge.fury.io/py/django-filer.svg
     :target: http://badge.fury.io/py/django-filer

docs/upgrading.rst

@@ -7,6 +7,25 @@ Usually upgrade procedure is straightforward: update the package and run migrati
 require special attention from the developer and here we provide upgrade instructions for such cases.
 
 
+from 3.x to 3.3
+---------------
+
+django-filer version 3.3 contains a change in security policy for file uploads.
+**By default, binary file or files of unknown type are not allowed to be uploaded.**
+To allow upload of binary files in your project, add
+
+.. code-block:: python
+
+    FILER_REMOVE_FILE_VALIDATORS = [
+        "application/octet-stream",
+    ]
+
+to your project's settings. Be aware that binary files always are a security risk.
+See :ref:`check_virus` for more information on how to configure file upload validators,
+e.g., running files through a virus checker.
+
+
+
 from 2.x to 3.0
 ---------------
 

docs/usage.rst

@@ -42,9 +42,11 @@ Simple example ``models.py``::
     class Company(models.Model):
         name = models.CharField(max_length=255)
         logo = FilerImageField(null=True, blank=True,
-                               related_name="logo_company")
+                             related_name="logo_company",
+                             on_delete=models.SET_NULL)
         disclaimer = FilerFileField(null=True, blank=True,
-                                    related_name="disclaimer_company")
+                                  related_name="disclaimer_company",
+                                  on_delete=models.SET_NULL)
 
 multiple file fields on the same model::
 
@@ -53,12 +55,21 @@ multiple file fields on the same model::
 
     class Book(models.Model):
         title = models.CharField(max_length=255)
-        cover = FilerImageField(related_name="book_covers")
-        back = FilerImageField(related_name="book_backs")
+        cover = FilerImageField(related_name="book_covers",
+                              on_delete=models.CASCADE)
+        back = FilerImageField(related_name="book_backs",
+                             on_delete=models.CASCADE)
 
-As with `django.db.models.ForeignKey`_ in general, you have to define a
-non-clashing ``related_name`` if there are multiple ``ForeignKey`` s to the
-same model.
+As with `django.db.models.ForeignKey`_ in general:
+
+* You must specify an ``on_delete`` parameter to define what happens when the referenced file is deleted
+* You have to define a non-clashing ``related_name`` if there are multiple ``ForeignKey`` s to the same model
+
+Common ``on_delete`` options:
+
+* ``models.CASCADE`` - Delete the model containing the FilerFileField when the referenced file is deleted
+* ``models.SET_NULL`` - Set the reference to NULL when the file is deleted (requires ``null=True``)
+* ``models.PROTECT`` - Prevent deletion of the referenced file
 
 templates
 .........

docs/validation.rst

@@ -264,6 +264,8 @@ If you distinguish validation by the mime type, remember to register the
 validator function for all relevant mime types.
 
 
+.. _check_virus:
+
 Checking uploads for viruses using ClamAV
 -----------------------------------------