Merge pull request #1727 from ckan/1193-deprecate-get-action-helper-s…

…econd-try

[#1193] Deprecate helpers.get_action()

CHANGELOG.rst

@@ -7,6 +7,29 @@
 Changelog
 ---------
 
+v2.3
+====
+
+API changes and deprecations
+----------------------------
+
+* ``helpers.get_action()`` (or ``h.get_action()`` in templates) is deprecated.
+
+  Since action functions raise exceptions and templates cannot catch
+  exceptions, it's not a good idea to call action functions from templates.
+
+  Instead, have your controller method call the action function and pass the
+  result to your template using the ``extra_vars`` param of ``render()``.
+
+  Alternatively you can wrap individual action functions in custom template
+  helper functions that handle any exceptions appropriately, but this is likely
+  to make your the logic in your templates more complex and templates are
+  difficult to test and debug.
+
+  Note that logic.get_action() and toolkit.get_action() are *not* deprecated,
+  core code and plugin code should still use ``get_action()``.
+
+
 v2.2 2014-02-04
 ===============
 

ckan/lib/helpers.py

@@ -737,8 +737,12 @@ def check_access(action, data_dict=None):
     return authorized
 
 
+@maintain.deprecated("helpers.get_action() is deprecated and will be removed "
+                     "in a future version of CKAN. Instead, please use the "
+                     "extra_vars param to render() in your controller to pass "
+                     "results from action functions to your templates.")
 def get_action(action_name, data_dict=None):
-    '''Calls an action function from a template.'''
+    '''Calls an action function from a template. Deprecated in CKAN 2.3.'''
     if data_dict is None:
         data_dict = {}
     return logic.get_action(action_name)({}, data_dict)

doc/contributing/architecture.rst

@@ -160,21 +160,32 @@ the helper functions found in ``ckan.lib.helpers.__allowed_functions__``.
 Deprecation
 -----------
 
-- Anything that may be used by extensions (see :doc:`/extensions/index`) needs
-  to maintain backward compatibility at call-site.  ie - template helper
-  functions and functions defined in the plugins toolkit.
+- Anything that may be used by :doc:`extensions </extensions/index>`,
+  :doc:`themes </theming/index>` or :doc:`API clients </api/index>` needs to
+  maintain backward compatibility at call-site. For example: action functions,
+  template helper functions and functions defined in the plugins toolkit.
 
 - The length of time of deprecation is evaluated on a function-by-function
-  basis.  At minimum, a function should be marked as deprecated during a point
+  basis. At minimum, a function should be marked as deprecated during a point
   release.
 
-- To mark a helper function, use the ``deprecated`` decorator found in
-  ``ckan.lib.maintain`` eg: ::
-
-    @deprecated()
-    def facet_items(*args, **kwargs):
-        """
-        DEPRECATED: Use the new facet data structure, and `unselected_facet_items()`
-        """
-        # rest of function definition.
-
+- To deprecate a function use the :py:func:`ckan.lib.maintain.deprecated`
+  decorator and add "deprecated" to the function's docstring::
+
+    @maintain.deprecated("helpers.get_action() is deprecated and will be removed "
+                        "in a future version of CKAN. Instead, please use the "
+                        "extra_vars param to render() in your controller to pass "
+                        "results from action functions to your templates.")
+    def get_action(action_name, data_dict=None):
+        '''Calls an action function from a template. Deprecated in CKAN 2.3.'''
+        if data_dict is None:
+            data_dict = {}
+        return logic.get_action(action_name)({}, data_dict)
+
+- Any deprecated functions should be added to an *API changes and deprecations*
+  section in the :doc:`/changelog` entry for the next release (do this before
+  merging the deprecation into master)
+
+- Keep the deprecation messages passed to the decorator short, they appear in
+  logs. Put longer explanations of why something was deprecated in the
+  changelog.