From 254c4990c18de8d3fef5c55ef8fa1f347433a252 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Fri, 20 Dec 2013 13:59:08 +0100 Subject: [PATCH] [#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 | 1 + doc/{ => contributing}/release-process.rst | 20 +++- doc/upgrading.rst | 103 +++++---------------- 3 files changed, 39 insertions(+), 85 deletions(-) rename doc/{ => contributing}/release-process.rst (95%) diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst index f2e62229d36..18692fa6220 100644 --- a/doc/contributing/index.rst +++ b/doc/contributing/index.rst @@ -35,3 +35,4 @@ of contributions to CKAN: database-migrations upgrading-dependencies + release-process diff --git a/doc/release-process.rst b/doc/contributing/release-process.rst similarity index 95% rename from doc/release-process.rst rename to doc/contributing/release-process.rst index 9c7e9e9073d..50a23773009 100644 --- a/doc/release-process.rst +++ b/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 diff --git a/doc/upgrading.rst b/doc/upgrading.rst index 3f433d5ae98..84433a4a157 100644 --- a/doc/upgrading.rst +++ b/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 `_, +a low-volume list that CKAN instance maintainers can subscribe to in order to +be up to date with upcoming releases. .. _upgrading: