Merge pull request #3111 from torfsen/improve-extension-best-practices

Improve extension best practices

ckan/pastertemplates/template/MANIFEST.in_tmpl

@@ -1,2 +1,4 @@
 include README.rst
+include LICENSE
+include requirements.txt
 recursive-include ckanext/{{ project_shortname }} *.html *.json *.js *.less *.css *.mo

ckan/pastertemplates/template/setup.py_tmpl

@@ -56,11 +56,12 @@ setup(
     packages=find_packages(exclude=['contrib', 'docs', 'tests*']),
     namespace_packages=['ckanext'],
 
-    # List run-time dependencies here.  These will be installed by pip when your
-    # project is installed. For an analysis of "install_requires" vs pip's
-    # requirements files see:
-    # https://packaging.python.org/en/latest/technical.html#install-requires-vs-requirements-files
-    install_requires=[],
+    install_requires=[
+      # CKAN extensions should not list dependencies here, but in a separate
+      # ``requirements.txt`` file.
+      #
+      # http://docs.ckan.org/en/latest/extensions/best-practices.html#add-third-party-libraries-to-requirements-txt
+    ],
 
     # If there are data files included in your packages that need to be
     # installed, specify them here.  If using Python 2.6 or less, then these
@@ -81,8 +82,9 @@ setup(
     entry_points='''
         [ckan.plugins]
         {{ project_shortname }}=ckanext.{{ project_shortname }}.plugin:{{ plugin_class_name }}
-	[babel.extractors]
-	ckan = ckan.lib.extract:extract_ckan
+
+        [babel.extractors]
+        ckan = ckan.lib.extract:extract_ckan
     ''',
 
     # If you are changing from the default layout of your extension, you may

doc/extensions/best-practices.rst

@@ -67,12 +67,28 @@ adding them to ``setup.py``, they should be added
 to ``requirements.txt``, which can be installed with::
 
   pip install -r requirements.txt
-  
+
 To prevent accidental breakage of your extension through backwards-incompatible 
 behaviour of newer versions of your dependencies, their versions should be pinned, 
 such as::
 
   requests==2.7.0
-  
+
 On the flip side, be mindful that this could also create version conflicts with
 requirements of considerably newer or older extensions.
+
+
+--------------------------------------------------
+Do not automatically modify the database structure
+--------------------------------------------------
+
+If your extension uses custom database tables then it needs to modify the
+database structure, for example to add the tables after its installation or to
+migrate them after an update. These modifications should not be performed
+automatically when the extension is loaded, since this can lead to `dead-locks
+and other problems`_.
+
+Instead, create a :doc:`paster command </maintaining/paster>` which can be run separately.
+
+.. _dead-locks and other problems: https://github.com/ckan/ideas-and-roadmap/issues/164
+