[#2977] Document requirement to namespace Redis keys.

Documents that Redis keys should be prefixed with the site ID and the
extension name.

doc/extensions/best-practices.rst

@@ -37,17 +37,57 @@ Implement each plugin class in a separate Python module
 This keeps CKAN's plugin loading order simple, see :ref:`ckan.plugins`.
 
 
-.. _extension config setting names best practice:
+.. _avoid name clashes:
 
------------------------------------------------------------------
-Names of config settings should include the name of the extension
------------------------------------------------------------------
+------------------
+Avoid name clashes
+------------------
+Many of the names you pick for your identifiers and files must be unique in
+relation to the names used by core CKAN and other extensions. To avoid
+conflicts you should prefix any public name that your extension introduces with
+the name of your extension. For example:
 
-Names of config settings provided by extensions should include the name
-of the extension, to avoid conflicting with core config settings or with
-config settings from other extensions. For example::
+* The names of *configuration settings* introduced by your extension should
+  have the form ``ckan.my_extension.my_config_setting``.
 
-  ckan.my_extension.show_most_popular_groups = True
+* The names of *templates and template snippets* introduced by your extension
+  should begin with the name of your extension::
+
+      snippets/my_extension_useful_snippet.html
+
+  If you have add a lot of templates you can also put them into a separate
+  folder named after your extension instead.
+
+* The names of *template helper functions* introduced by your extension should
+  begin with the name of your extension. For example:
+
+  .. literalinclude:: /../ckanext/example_theme/v08_custom_helper_function/plugin.py
+     :pyobject: ExampleThemePlugin.get_helpers
+
+* The names of *JavaScript modules* introduced by your extension should begin
+  with the name of your extension. For example
+  ``fanstatic/example_theme_popover.js``:
+
+  .. literalinclude:: /../ckanext/example_theme/v16_initialize_a_javascript_module/fanstatic/example_theme_popover.js
+
+* The names of *API action functions* introduced by your extension should begin
+  with the name of your extension. For example
+  ``my_extension_foobarize_everything``.
+
+In some situations, resources like databases may even be shared between
+multiple CKAN *instances*, which requires an even higher degree of uniqueness
+for the corresponding names. In that case, you should also prefix your
+identifiers with the CKAN site ID, which is available via
+
+::
+
+    from pylons import config
+    site_id = config[u'ckan.site_id']
+
+Currently this only affects the :ref:`Redis database <redis_url>`:
+
+* All *keys in the Redis database* created by your extension should be prefixed
+  with both the CKAN site ID and your extension's name.
 
 
 -------------------------------------

doc/extensions/custom-config-settings.rst

@@ -32,7 +32,7 @@ will be allowed to create groups.
    Names of config settings provided by extensions should include the name
    of the extension, to avoid conflicting with core config settings or with
    config settings from other extensions.
-   See :ref:`extension config setting names best practice`.
+   See :ref:`avoid name clashes`.
 
 .. note::
 

doc/theming/best-practices.rst

@@ -50,42 +50,12 @@ All user-visible strings should be internationalized, see
 :doc:`/contributing/string-i18n`.
 
 
------------------------------------------------------------------
-Helper function names should begin with the name of the extension
------------------------------------------------------------------
+------------------
+Avoid name clashes
+------------------
 
-Namespacing helper functions in this way avoids accidentally overriding, or
-being overriden by, a core helper function, or a helper function from another
-extension. For example:
+See :ref:`avoid name clashes`.
 
-.. literalinclude:: /../ckanext/example_theme/v08_custom_helper_function/plugin.py
-   :pyobject: ExampleThemePlugin.get_helpers
-
-
-.. _snippet filenames best practice:
-
--------------------------------------------------------------
-Snippet filenames should begin with the name of the extension
--------------------------------------------------------------
-
-Namespacing snippets in this way avoids accidentally overriding, or being
-overridden by, a core snippet, or a snippet from another extension.
-For example::
-
- snippets/example_theme_most_popular_groups.html
-
-
-.. _javascript module names best practice:
-
-----------------------------------------------------------------------
-|javascript| modules names should begin with the name of the extension
-----------------------------------------------------------------------
-
-Namespacing |javascript| modules in this way avoids accidentally overriding, or
-being overridden by, a core module, or a module from another extension.  For
-example: ``fanstatic/example_theme_popover.js``:
-
-.. literalinclude:: /../ckanext/example_theme/v16_initialize_a_javascript_module/fanstatic/example_theme_popover.js
 
 .. _javascript module docstrings best practice:
 

doc/theming/javascript.rst

@@ -88,8 +88,7 @@ To get CKAN to call some custom JavaScript code, we need to:
    .. note::
 
       |javascript| module names should begin with the name of the extension,
-      to avoid conflicting with other modules.
-      See :ref:`javascript module names best practice`.
+      to avoid conflicting with other modules. See :ref:`avoid name clashes`.
 
    .. note::
 

doc/theming/templates.rst

@@ -657,8 +657,7 @@ should see the most popular groups rendered differently:
 
    To avoid unintended conflicts, we recommend that snippet filenames begin
    with the name of the extension they belong to, e.g.
-   ``snippets/example_theme_*.html``.
-   See :ref:`snippet filenames best practice`.
+   ``snippets/example_theme_*.html``. See :ref:`avoid name clashes`.
 
 .. note::
 
@@ -754,8 +753,7 @@ the most popular groups on the front page. First, add a new helper function to
 
    Names of config settings provided by extensions should include the name
    of the extension, to avoid conflicting with core config settings or with
-   config settings from other extensions.
-   See :ref:`extension config setting names best practice`.
+   config settings from other extensions. See :ref:`avoid name clashes`.
 
 Now we can call this helper function from our ``layout1.html`` template: