Repository: wagtail/wagtail

Issue:
Possibly incorrect hook names?
Going through the docs, I see two rather unusual hook names: `construct_wagtail_edit_bird` and `construct_whitelister_element_rules`. 

The first seems like a placeholder name that accidentally made it out of the alpha stage. Based on the docs, it seems like it should be called `construct_wagtail_userbar`.

The second seems like a straight up typo. I've never heard the word "whitelister" before. I'm pretty sure this hook should be called `construct_whitelisted_element_rules`.

Changing the names of hooks is obviously a major undertaking, since some code bases will have already implemented them. But adding the new names and deprecating the old ones for a few releases should be entirely possible. I'd be happy to do this in a pull request, since it's only a dozen or lines of code to change, but I don't really know how wagtail handles deprecating old APIs.

Possibly incorrect hook names?
Going through the docs, I see two rather unusual hook names: `construct_wagtail_edit_bird` and `construct_whitelister_element_rules`. 

The first seems like a placeholder name that accidentally made it out of the alpha stage. Based on the docs, it seems like it should be called `construct_wagtail_userbar`.

The second seems like a straight up typo. I've never heard the word "whitelister" before. I'm pretty sure this hook should be called `construct_whitelisted_element_rules`.

Changing the names of hooks is obviously a major undertaking, since some code bases will have already implemented them. But adding the new names and deprecating the old ones for a few releases should be entirely possible. I'd be happy to do this in a pull request, since it's only a dozen or lines of code to change, but I don't really know how wagtail handles deprecating old APIs.



Discussion:
Hi @coredumperror,

From what I can gather, the deprecation rules are as follows:
- A deprecation warning is added when the change is made. Corresponding release notes must added. See http://docs.wagtail.io/en/latest/releases/0.4.html#deprecated-features
- The features get deprecated two point releases later. e.g. http://docs.wagtail.io/en/latest/releases/0.6.html#all-features-deprecated-in-0-4-have-been-removed

You can find the DeprecationWarning and how they were used by viewing the history for `wagtail/utils/deprecation.py`. Specifically, look at https://github.com/torchbox/wagtail/blob/9eabdc374bd6176fc52573b6c10d2cfb7e1c5d44/wagtail/wagtailsearch/indexed.py

The one thing that stands out is that master has `RemovedInWagtail10Warning` rather than `RemovedInWagtail09Warning`. @kaedroho, please correct me if I am missing something obvious.

All features that were removed in 0.9 have been removed from master so there's no need for `RemovedInWagtail09Warning`.

Hi @coredumperror,

From what I can gather, the deprecation rules are as follows:
- A deprecation warning is added when the change is made. Corresponding release notes must added. See http://docs.wagtail.io/en/latest/releases/0.4.html#deprecated-features
- The features get deprecated two point releases later. e.g. http://docs.wagtail.io/en/latest/releases/0.6.html#all-features-deprecated-in-0-4-have-been-removed

You can find the DeprecationWarning and how they were used by viewing the history for `wagtail/utils/deprecation.py`. Specifically, look at https://github.com/torchbox/wagtail/blob/9eabdc374bd6176fc52573b6c10d2cfb7e1c5d44/wagtail/wagtailsearch/indexed.py

The one thing that stands out is that master has `RemovedInWagtail10Warning` rather than `RemovedInWagtail09Warning`. @kaedroho, please correct me if I am missing something obvious.

All features that were removed in 0.9 have been removed from master so there's no need for `RemovedInWagtail09Warning`.


Resolving patch:
diff --git a/wagtail/wagtailadmin/views/userbar.py b/wagtail/wagtailadmin/views/userbar.py
--- a/wagtail/wagtailadmin/views/userbar.py
+++ b/wagtail/wagtailadmin/views/userbar.py
@@ -1,3 +1,5 @@
+import warnings
+
 from django.shortcuts import render
 from django.contrib.auth.decorators import permission_required
 
@@ -5,6 +7,8 @@
 from wagtail.wagtailcore import hooks
 from wagtail.wagtailcore.models import Page, PageRevision
 
+from wagtail.utils.deprecation import RemovedInWagtail11Warning
+
 
 @permission_required('wagtailadmin.access_admin', raise_exception=True)
 def for_frontend(request, page_id):
@@ -13,7 +17,10 @@ def for_frontend(request, page_id):
         AddPageItem(Page.objects.get(id=page_id)),
     ]
 
-    for fn in hooks.get_hooks('construct_wagtail_edit_bird'):
+    # TODO: Remove in 1.1 release
+    run_deprecated_edit_bird_hook(request, items)
+
+    for fn in hooks.get_hooks('construct_wagtail_userbar'):
         fn(request, items)
 
     # Render the items
@@ -37,7 +44,10 @@ def for_moderation(request, revision_id):
         RejectModerationEditPageItem(PageRevision.objects.get(id=revision_id)),
     ]
 
-    for fn in hooks.get_hooks('construct_wagtail_edit_bird'):
+    # TODO: Remove in 1.1 release
+    run_deprecated_edit_bird_hook(request, items)
+
+    for fn in hooks.get_hooks('construct_wagtail_userbar'):
         fn(request, items)
 
     # Render the items
@@ -50,3 +60,13 @@ def for_moderation(request, revision_id):
     return render(request, 'wagtailadmin/userbar/base.html', {
         'items': rendered_items,
     })
+
+
+def run_deprecated_edit_bird_hook(request, items):
+    for fn in hooks.get_hooks('construct_wagtail_edit_bird'):
+        fn(request, items)
+
+        warnings.warn(
+            "The 'construct_wagtail_edit_bird' hook has been renamed to 'construct_wagtail_userbar'."
+            "Please update function '%s' in '%s'." % (fn.__name__, fn.__module__), RemovedInWagtail11Warning
+        )


Test patch: