Update docs for on_delete requirement in Filer fields for Django 5.1 (#1508)

* Update docs for on_delete requirement in Filer fields for Django 5.1

Update documentation to reflect the requirement of the `on_delete` parameter for `FilerFileField` and `FilerImageField`, ensuring compatibility with Django 5.1.

Documentation:
- Update documentation to indicate that the `on_delete` parameter is required when using `FilerFileField` and `FilerImageField`.
- Add example code in the documentation showing proper field definition with the `on_delete` parameter.
- Review and update other field examples in the documentation to ensure they include required parameters.

Resolves #1506

* Collect upgrading info at one palce

* Update version and changelog

---------

Co-authored-by: sourcery-ai[bot] <sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: Fabian Braun <[email protected]>

Author: sourcery-ai[bot]

CHANGELOG.rst

@@ -2,6 +2,14 @@
 CHANGELOG
 =========
 
+3.3.0 (2024-11-19)
+==================
+
+* fix: Restrict upload of binary or unknown file types by default by @fsbraun in https://github.com/django-cms/django-filer/pull/1507
+* fix: remove extra brace in generated HTML of data-max-filesize attribute by @fabien-michel in https://github.com/django-cms/django-filer/pull/1502
+* fix: uploadButton data-max-filesize attribute is not passed to file-uploader by @fabien-michel in https://github.com/django-cms/django-filer/pull/1503
+* docs: Update for on_delete requirement in Filer fields
+
 3.2.3 (2024-09-18)
 ==================
 

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
 -----------------------------------------
 

filer/__init__.py

@@ -13,4 +13,4 @@
  8. Publish the release and it will automatically release to pypi
 """
 
-__version__ = '3.2.3'
+__version__ = '3.3.0'