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

sourcery-ai[bot] · fsbraun · web-flow · commit 8f7f96f58a84 · 2024-11-19T17:24:18.000+01:00
* 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 <fsbraun@gmx.de>
diff --git a/CHANGELOG.rst b/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)
 ==================
 
diff --git a/README.rst b/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
diff --git a/docs/upgrading.rst b/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
 ---------------
 
diff --git a/docs/usage.rst b/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
 .........
diff --git a/docs/validation.rst b/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
 -----------------------------------------
 
diff --git a/filer/__init__.py b/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'
