Skip to content

Commit

Permalink
Merge branch '1389-release-docs-tweaks-2'
Browse files Browse the repository at this point in the history
  • Loading branch information
Sean Hammond committed Dec 20, 2013
2 parents 97855aa + 5e5a1c5 commit cac9247
Show file tree
Hide file tree
Showing 4 changed files with 52 additions and 117 deletions.
1 change: 1 addition & 0 deletions doc/contributing/index.rst
View file
Expand Up @@ -35,3 +35,4 @@ of contributions to CKAN:

database-migrations
upgrading-dependencies
release-process
63 changes: 27 additions & 36 deletions doc/release-process.rst → doc/contributing/release-process.rst
View file
@@ -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
Expand All @@ -26,17 +35,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::

<schema name="ckan" version="{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).
Expand Down Expand Up @@ -78,20 +76,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
Expand All @@ -100,11 +90,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

Expand All @@ -115,7 +105,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
Expand All @@ -125,27 +115,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 <https://www.transifex.com/projects/p/ckan/resource/2-0/>`_)
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
Expand All @@ -155,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
Expand Down Expand Up @@ -219,7 +210,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 <http://readthedocs.org/dashboard/ckan/versions/>`
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).

Expand Down Expand Up @@ -253,4 +244,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/
2 changes: 1 addition & 1 deletion doc/theming/fanstatic.rst
View file
Expand Up @@ -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.
103 changes: 23 additions & 80 deletions doc/upgrading.rst
View file
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit cac9247

Please sign in to comment.