Clarify return values of ..._on_commit methods (#8984)

* Clarify delay_on_commit documentation doesn't return the task ID

* Update signature for delay_on_commit and apply_async_on_commit

* Update tests

* Update docs/django/first-steps-with-django.rst

---------

Co-authored-by: Tomer Nosrati <tomer.nosrati@gmail.com>

celery/contrib/django/task.py

@@ -12,10 +12,10 @@ class DjangoTask(Task):
     Provide a nicer API to trigger tasks at the end of the DB transaction.
     """
 
-    def delay_on_commit(self, *args, **kwargs):
+    def delay_on_commit(self, *args, **kwargs) -> None:
         """Call :meth:`~celery.app.task.Task.delay` with Django's ``on_commit()``."""
-        return transaction.on_commit(functools.partial(self.delay, *args, **kwargs))
+        transaction.on_commit(functools.partial(self.delay, *args, **kwargs))
 
-    def apply_async_on_commit(self, *args, **kwargs):
+    def apply_async_on_commit(self, *args, **kwargs) -> None:
         """Call :meth:`~celery.app.task.Task.apply_async` with Django's ``on_commit()``."""
-        return transaction.on_commit(functools.partial(self.apply_async, *args, **kwargs))
+        transaction.on_commit(functools.partial(self.apply_async, *args, **kwargs))

docs/django/first-steps-with-django.rst

@@ -206,6 +206,11 @@ This API takes care of wrapping the call into the `on_commit`_ hook for you.
 In rare cases where you want to trigger a task without waiting, the existing
 :meth:`~celery.app.task.Task.delay` API is still available.
 
+One key difference compared to the ``delay`` method, is that ``delay_on_commit``
+will NOT return the task ID back to the caller. The task is not sent to the broker
+when you call the method, only when the Django transaction finishes. If you need the
+task ID, best to stick to :meth:`~celery.app.task.Task.delay`.
+
 This task class should be used automatically if you've follow the setup steps above.
 However, if your app :ref:`uses a custom task base class <task-custom-classes>`,
 you'll need inherit from :class:`~celery.contrib.django.task.DjangoTask` instead of

t/unit/contrib/django/test_task.py

@@ -25,8 +25,8 @@ def on_commit(self):
 
     def test_delay_on_commit(self, task_instance, on_commit):
         result = task_instance.delay_on_commit()
-        assert result is not None
+        assert result is None
 
     def test_apply_async_on_commit(self, task_instance, on_commit):
         result = task_instance.apply_async_on_commit()
-        assert result is not None
+        assert result is None