Merge branch '1155-document-upgrading-dependencies'

CONTRIBUTING.rst

@@ -61,13 +61,15 @@ When writing code for CKAN, try to respect our coding standards:
    css-coding-standards
    javascript-coding-standards
    testing-coding-standards
+   upgrading-dependencies
 
 * `CKAN coding standards <http://docs.ckan.org/en/latest/ckan-coding-standards.html>`_
 * `Python coding standards <http://docs.ckan.org/en/latest/python-coding-standards.html>`_
 * `HTML coding standards <http://docs.ckan.org/en/latest/html-coding-standards.html>`_
 * `CSS coding standards <http://docs.ckan.org/en/latest/css-coding-standards.html>`_
 * `JavaScript coding standards <http://docs.ckan.org/en/latest/javascript-coding-standards.html>`_
 * `Testing coding standards <http://docs.ckan.org/en/latest/testing-coding-standards.html>`_
+* `Upgrading CKAN's dependencies <http://docs.ckan.org/en/latest/upgrading-dependencies.html>`_
 
 
 ---------------

doc/upgrading-dependencies.rst

@@ -0,0 +1,62 @@
+--------------------------
+Upgrading the dependencies
+--------------------------
+
+The Python modules that CKAN depends on are pinned to specific versions, so we
+can guarantee that whenever anyone installs CKAN, they'll always get the same
+versions of the Python modules in their virtual environment.
+
+Our dependencies are defined in three files:
+
+requirements.in
+  This file is only used to create a new version of the ``requirements.txt``
+  file when upgrading the dependencies.
+  Contains our direct dependencies only (not dependencies of dependencies)
+  with loosely defined versions. For example, ``apachemiddleware>=0.1.1,<0.2``.
+
+requirements.txt
+  This is the file that people actually use to install CKAN's dependencies into
+  their virtualenvs. It contains every dependency, including dependencies of
+  dependencies, each pinned to a specific version.
+  For example, ``simplejson==3.3.1``.
+
+dev-requirements.txt
+  Contains those dependencies only needed by developers, not needed for
+  production sites. These are pinned to a specific version. For example,
+  ``factory-boy==2.1.1``.
+
+We haven't created a ``dev-requirements.in`` file because we have too few dev
+dependencies, we don't update them often, and none of them have a known
+incompatible version.
+
+Steps to upgrade
+================
+
+These steps will upgrade all of CKAN's dependencies to the latest versions that
+work with CKAN:
+
+#. Create a new virtualenv: ``virtualenv --no-site-packages upgrading``
+
+#. Install the requirements with unpinned versions: ``pip install -r
+   requirements.in``
+
+#. Save the new dependencies versions: ``pip freeze > requirements.txt``. We
+   have to do this before installing the other dependencies so we get only what
+   was in ``requirements.in``
+
+#. Install CKAN: ``python setup.py develop``
+
+#. Install the development dependencies: ``pip install -r
+   dev-requirements.txt``
+
+#. Run the tests to make sure everything still works (see :doc:`test`).
+
+   - If not, try to fix the problem. If it's too complicated, pinpoint which
+     dependency's version broke our tests, find an older version that still
+     works, and add it to ``requirements.in`` (i.e., if ``python-dateutil``
+     2.0.0 broke CKAN, you'd add ``python-dateutil>=1.5.0,<2.0.0``). Go back to
+     step 1.
+
+#. Navigate a bit on CKAN to make sure the tests didn't miss anything. Review
+   the dependencies changes and their changelogs. If everything seems fine, go
+   ahead and make a pull request (see :ref:`making a pull request`).