[#1389] Reorganize the release process docs a little

Put all the stuff that users need to know (what the different types of
release are, and how to upgrade) in /upgrading.html, and put all the
stuff for developers only (how to do a CKAN release) in /contributing/.
Use ..  seealso:: boxes to link the two pages together. Also removed
some duplicated information, fixed some title styles, etc.

doc/contributing/index.rst

@@ -35,3 +35,4 @@ of contributions to CKAN:
 
    database-migrations
    upgrading-dependencies
+   release-process

doc/release-process.rst → doc/contributing/release-process.rst

@@ -1,12 +1,21 @@
-Doing a CKAN Release
 ====================
+Doing a CKAN release
+====================
+
+This section documents the steps followed by the development team to do a
+new CKAN release.
+
+.. seealso::
+
+   :doc:`/upgrading`
+     An overview of the different kinds of CKAN release, and the process for
+     upgrading a CKAN site to a new version.
 
-These are the steps followed by CKAN developers to do a release. To get an
-overview of CKAN releases, check :doc:`upgrading`.
 
 .. _beta-release:
 
-Doing a Beta Release
+--------------------
+Doing a beta release
 --------------------
 
 Beta releases are branched off a certain point in master and will eventually
@@ -136,7 +145,8 @@ become stable releases.
         git push
 
 
-Doing a Proper Release
+----------------------
+Doing a proper release
 ----------------------
 
 Once the release branch has been thoroughly tested and is stable we can do

doc/upgrading.rst

@@ -2,17 +2,18 @@
 Upgrading CKAN
 ==============
 
-This document covers CKAN releases and how to upgrade a site to a newer version
-of CKAN:
+This document describes the different types of CKAN release, and explains
+how to upgrade a site to a newer version of CKAN.
 
-* :ref:`releases` describes the different types of CKAN release
-* :ref:`release process` describes the process that the CKAN dev team follows,
-  when we make a new CKAN release
-* Finally, :ref:`upgrading` will walk you through the steps for upgrading a
-  CKAN site to a newer version of CKAN
+.. seealso::
 
-For a list of CKAN releases and the changes introduced in each release, see the
-:doc:`changelog`.
+   :doc:`changelog`
+     The changelog lists all CKAN releases and the main changes introduced in
+     each release.
+
+   :doc:`/contributing/release-process`
+     Documentation of the process that the CKAN developers follow to do a
+     CKAN release.
 
 
 .. _releases:
@@ -23,7 +24,6 @@ CKAN releases
 
 CKAN follows a predictable release cycle so that users can depend on stable
 releases of CKAN, and can plan their upgrades to new releases.
-The :doc:`changelog` documents the main changes in each release.
 
 Each release has a version number of the form ``M.m`` (eg. 2.1) or ``M.m.p``
 (eg. 1.8.2), where ``M`` is the **major version**, ``m`` is the **minor
@@ -55,79 +55,22 @@ Patch Releases
   - New dependencies
   - Big refactorings or new features in critical parts of the code
 
-Users should always run the latest patch release for the minor release they
-are on, as they contain important bug fixes and security updates. As they
-don't include backwards incompatible changes, the upgrade process (as
-described in :doc:`upgrade-package-to-patch-release`) should be
-straightforward.
-
-Outdated patch releases will no longer be supported after a newer patch
-release has been released. For example once CKAN 2.0.2 has been released,
-CKAN 2.0.1 will no longer be supported.
-
-Releases are announced on the ``ckan-announce`` mailing list, a low-volume
-list that CKAN instance maintainers can subscribe to in order to be up to date
-with upcoming releases. You can sign up to the list here:
-
-http://lists.okfn.org/mailman/listinfo/ckan-announce
-
-.. _release process:
-
----------------
-Release process
----------------
-
-.. _beta.ckan.org: http://beta.ckan.org
-.. _Transifex: https://www.transifex.com/projects/p/ckan
-
-When the development is ready to start the process of releasing a new version
-of CKAN, we will:
-
-#. Create a new release branch from the master branch, named ``release-v*``
-   where ``*`` is the release's version number.
-
-#. Deploy the release branch on `beta.ckan.org`_ for testing.
-
-#. During the next two-three weeks, we'll allow changes on the release branch
-   only to stabilize the code, update translations and documentation, etc.
-   (new features are usually not added on the release branch).
-
-#. During the final week before the release, we'll only allow critical bug
-   fixes to be committed on the release branch.
-
-.. _ckan-dev: http://lists.okfn.org/mailman/listinfo/ckan-dev
-.. _ckan-discuss: http://lists.okfn.org/mailman/listinfo/ckan-discuss
-.. _ckan-announce: http://lists.okfn.org/mailman/listinfo/ckan-announce
-
-At some point during the beta period a **strings freeze** will begin.
-That means that no changes to translatable strings are allowed on the release
-branch (no new strings, or changes to existing strings). This will give
-translators time to update the translations on Transifex_. We'll publish a
-**call for translations** to the `ckan-dev`_ and `ckan-discuss`_ mailing
-lists, announcing that the new version is ready to be translated.
-
-At some point before the final release, we'll announce an **end of
-translations** after which no new translations will be pulled into the release
-branch. At this point we'll deploy the translations to `beta.ckan.org`_ and
-we'll put out a request for people to test CKAN in their languages.
-
-The upcoming releases are announced on the `ckan-announce`_ mailing list.
-
-Release branches are not merged back into master. All changes on a release
-branch are cherry-picked from master (or merged from special branches based on
-the release branch).
-
-To ensure that the release guidelines are enforced one of the CKAN core
-developers will act as **Release Manager**. They have the final say on what is
-merged into the release branches.
+.. note::
 
-Detailed release process instructions for CKAN Developers can be found in the
-:doc:`release-process` document:
+   Users should always run the latest patch release for the minor release they
+   are on, as patch releases contain important bug fixes and security updates.
+   Because patch releases don't include backwards incompatible changes, the
+   upgrade process (as described in :doc:`upgrade-package-to-patch-release`)
+   should be straightforward.
 
-.. toctree::
-   :maxdepth: 1
+   Outdated patch releases will no longer be supported after a newer patch
+   release has been released. For example once CKAN 2.0.2 has been released,
+   CKAN 2.0.1 will no longer be supported.
 
-   release-process
+Releases are announced on the
+`ckan-announce mailing list <http://lists.okfn.org/mailman/listinfo/ckan-announce>`_,
+a low-volume list that CKAN instance maintainers can subscribe to in order to
+be up to date with upcoming releases.
 
 
 .. _upgrading: