From 1b4d639c0bb27f78700fb140b5012bb227f291fd Mon Sep 17 00:00:00 2001 From: amercader Date: Fri, 13 Dec 2013 13:46:23 +0000 Subject: [PATCH 1/3] [#1389] Tweak release process docs --- doc/release-process.rst | 43 ++++++++++++----------------------------- 1 file changed, 12 insertions(+), 31 deletions(-) diff --git a/doc/release-process.rst b/doc/release-process.rst index 4b427d2cf03..9c7e9e9073d 100644 --- a/doc/release-process.rst +++ b/doc/release-process.rst @@ -26,17 +26,6 @@ become stable releases. You will probably need to update the same file on master to increase the version number, in this case ending with an *a* (for alpha). -#. Check if there have been changes in the |solr| schema at - ``ckan/config/solr/schema.xml``, and if so: - - * Update the ``version`` attribute of the ``schema`` with the current CKAN - version:: - - - - * Update the ``SUPPORTED_SCHEMA_VERSIONS`` list in - ``ckan/lib/search/__init__.py`` - #. During the beta process, all changes to the release branch must be cherry-picked from master (or merged from special branches based on the release branch if the original branch was not compatible). @@ -78,20 +67,12 @@ become stable releases. python setup.py extract_messages - d. Pull new and updated translations from Transifex into the ``ckan.po`` - files:: - - tx pull --all --force - The po files are text files, one for each language CKAN is translated to, that contain the translated strings next to the originals. Translators edit the po files (on Transifex) to update the translations. We never edit the po files locally. - ``--force`` tells Transifex to update all ``ckan.po`` files, regardless of the - modification time. - - e. Run our script that checks for mistakes in the ckan.po files:: + d. Run our script that checks for mistakes in the ckan.po files:: pip install polib paster check-po-files ckan/i18n/*/LC_MESSAGES/ckan.po @@ -100,11 +81,11 @@ become stable releases. tx pull command again, don't edit the files directly. Repeat until the script finds no mistakes. - f. Edit ``.tx/config``, on line 4 to set the Transifex 'resource' to the new + e. Edit ``.tx/config``, on line 4 to set the Transifex 'resource' to the new major release name (if different), using dashes instead of dots. For instance v1.2, v1.2.1 and v1.2.2 all share: ``[ckan.1-2]``. - g. Update the ``ckan.po`` files with the new strings from the ``ckan.pot`` file:: + f. Update the ``ckan.po`` files with the new strings from the ``ckan.pot`` file:: python setup.py update_catalog --no-fuzzy-matching @@ -115,7 +96,7 @@ become stable releases. We use the ``--no-fuzzy-matching`` option because fuzzy matching often causes problems with Babel and Transifex. - h. Create a new resource in the CKAN project on Transifex by pushing the new + g. Create a new resource in the CKAN project on Transifex by pushing the new pot and po files:: tx push --source --translations --force @@ -125,27 +106,27 @@ become stable releases. resource (updating an existing resource, especially with the ``--force`` option, can result in translations being deleted from Transifex). - i. Update the ``ckan.mo`` files by compiling the po files:: + h. Update the ``ckan.mo`` files by compiling the po files:: python setup.py compile_catalog The mo files are the files that CKAN actually reads when displaying strings to the user. - j. Commit all the above changes to git and push them to GitHub:: + i. Commit all the above changes to git and push them to GitHub:: - git commit -am " Update strings files before CKAN X.Y call for translations" + git commit -am "Update strings files before CKAN X.Y call for translations" git push - k. Announce that strings for the new release are ready for translators. Send + j. Announce that strings for the new release are ready for translators. Send an email to the mailing lists, tweet or post it on the blog. Make sure to post a link to the correct Transifex resource (like `this one `_) and tell users that they can register on Transifex to contribute. - l. A week before the translations will be closed send a reminder email. + k. A week before the translations will be closed send a reminder email. - m. Once the translations are closed, pull the updated strings from Transifex, + l. Once the translations are closed, pull the updated strings from Transifex, check them, compile and push as described in the previous steps:: tx pull --all --force @@ -219,7 +200,7 @@ a release. 8. Enable the new version of the docs on Read the Docs (you will need an admin account): - a. Go to the `versions page ` + a. Go to the `Read The Docs`_ versions page and enable the relevant release (make sure to use the tag, ie ckan-X.Y, not the branch, ie release-vX.Y). @@ -253,4 +234,4 @@ a release. .. _Transifex: https://www.transifex.com/projects/p/ckan -.. _ReadTheDocs: http://readthedocs.org/dashboard/ckan/versions/ +.. _`Read The Docs`: http://readthedocs.org/dashboard/ckan/versions/ From 254c4990c18de8d3fef5c55ef8fa1f347433a252 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Fri, 20 Dec 2013 13:59:08 +0100 Subject: [PATCH 2/3] [#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: From 5e5a1c5c8b71f016e8a892ed1608728a71fcde4c Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Fri, 20 Dec 2013 13:59:38 +0100 Subject: [PATCH 3/3] [#1389] Fix a Sphinx error --- doc/theming/fanstatic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/theming/fanstatic.rst b/doc/theming/fanstatic.rst index 0839cc84d9f..35c2528fd24 100644 --- a/doc/theming/fanstatic.rst +++ b/doc/theming/fanstatic.rst @@ -63,4 +63,4 @@ to serve the CSS file with Fanstatic. A config file can be used to configure how Fanstatic should serve each resource file (whether or not to bundle files, what order to include files in, whether to include files at the top or bottom of the page, dependencies between files, - etc.) See :doc:`/resources` for details. + etc.) See :doc:`/contributing/frontend/resources` for details.