191 lines
7.3 KiB
Text
191 lines
7.3 KiB
Text
================================
|
|
Some notes on hacking on kitchen
|
|
================================
|
|
|
|
:Author: Toshio Kuratomi
|
|
:Date: 2 Jan 2012
|
|
:Version: 1.1.x
|
|
|
|
For coding and kitchen, see the style guide in the documentation.
|
|
|
|
This file documents meta-information about kitchen such as where to get the
|
|
code and how to make a release.
|
|
|
|
.. contents::
|
|
|
|
-----------------------------------------
|
|
Extra software needed for making releases
|
|
-----------------------------------------
|
|
Although kitchen has very few requirements for running, there are a few more
|
|
that are required for making a release:
|
|
|
|
* python-2.4+ (tested on python-2.7)
|
|
* transifex-client (/usr/bin/tx)
|
|
* gettext (/usr/bin/msgfmt)
|
|
* python-babel (/usr/bin/pybabel)
|
|
* python-sphinx (/usr/bin/sphinx-build)
|
|
* python-nose (/usr/bin/nosetests)
|
|
* python-coverage (/usr/bin/coverage)
|
|
|
|
--------------
|
|
Get translated
|
|
--------------
|
|
|
|
We use the translation services at transifex.net to manage po files, coordinate
|
|
people translating strings, and merge new strings to the files. The following
|
|
instructions briefly tell how to use transifex to update the source languages'
|
|
files and pull new translations for release. Actually doing translations can
|
|
be found in the `transifex user's guide`_.
|
|
|
|
.. `transifex user's guide`:: http://help.transifex.net/user-guide/translating.html
|
|
|
|
To generate the POT file (located in the po/ subdirectory), use pybabel to
|
|
extract the messages. Tun the following from the top level directory::
|
|
|
|
pybabel extract -o po/kitchen.pot kitchen -kb_ -kbN_
|
|
|
|
Then commit this pot file and upload to transifex::
|
|
|
|
tx push -s
|
|
bzr commit -m 'Extract new strings from the source files' po/kitchen.pot
|
|
bzr push
|
|
|
|
To pull messages from transifex prior to making a release, do::
|
|
|
|
tx pull -a
|
|
bzr commit -m 'Merge new translations from transifex' po/*.po
|
|
|
|
If you see a status message from transifex like this::
|
|
Pulling new translations for resource kitchen.kitchenpot (source: po/kitchen.pot)
|
|
-> fr: po/fr.po
|
|
|
|
it means that transifex has created a brand new po file for you. You need to
|
|
add the new file to source control and commit it like this::
|
|
|
|
bzr add po/fr.po
|
|
bzr commit -m 'New French translation' po/fr.po
|
|
|
|
|
|
TODO: Add information about announcing string freeze. Using transifex's add
|
|
release function to coordinate with translators. Mailing a translators list,
|
|
etc.
|
|
|
|
--------
|
|
Releases
|
|
--------
|
|
|
|
.. note:: If a release is not time critical, make an effort to get the
|
|
software translated first. See :id:`Get translated` for details.
|
|
|
|
Testing
|
|
=======
|
|
|
|
Even though python is a compiled language, there's several ways to test that
|
|
the software is correct.
|
|
|
|
Test that docs build
|
|
--------------------
|
|
|
|
Documentation is written in ReStructuredText format and built via the
|
|
:mod:`sphinx` documentation system for python. There is a variety of
|
|
hand-written and formatted documentation in the :file:`docs` directory. Those
|
|
documents also pull some documentation out of the docstrings in the code.
|
|
|
|
Any of those places may have formatting that is not valid in the sphinx
|
|
system. Building the documentation into html will see if there's any spots
|
|
that need to be fixed::
|
|
|
|
python setup.py build_sphinx --fresh-env
|
|
|
|
The command will attempt to turn the documentation into html. Any errors or
|
|
warnings in the output mean that there's some piece of documentation that
|
|
sphinx doesn't know how to deal with. That should be fixed before publishing
|
|
the release.
|
|
|
|
|
|
Test that message catalogs compile
|
|
----------------------------------
|
|
|
|
One of the pieces of creating a new release is downloading new message
|
|
catalogs from transifex. Once in a great while, a translator will upload a
|
|
translation there that causes problems (for instance, adding or omitting
|
|
format strings from a translated string.) Luckily the commands to create the
|
|
message catalogs will detect things like this so just compiling the catalogs
|
|
will determine if any translations need to be adjusted::
|
|
|
|
./releaseutils.py
|
|
|
|
This will iterate through all the message catalogs that transifex downloaded
|
|
to the :file:`po` directory and compile them into the :file:`locale`
|
|
directory.
|
|
|
|
.. warning:: If :file:/usr/bin/msgfmt is not installed, this command will still
|
|
compile the message catalogs but it will use babel. Babel, unfortunately,
|
|
doesn't check for all the errors in message catalogs that msgfmt does so
|
|
it may say that the messages are fine when they really aren't. Make sure
|
|
you have msgfmt available by installing gettext.
|
|
|
|
Unittest
|
|
--------
|
|
|
|
Kitchen has a large set of unittests. All of them should pass before release.
|
|
You can run the unittests with the following command::
|
|
nosetests --with-coverage --cover-package kitchen
|
|
|
|
This will run all the unittests under the tests directory and also generate
|
|
some statistics about which lines of code were not accessed when kitchen ran.
|
|
|
|
.. warning:: Although 100% test coverage is a worthy goal, it doesn't mean
|
|
that the code is bug free. This is especially true of code, like
|
|
kitchen's, that deals with encoding issues. The same piece of code in
|
|
kitchen will do different things depending on whether unicode or byte str
|
|
(and the characters that are in the byte str) is passed as a parameter and
|
|
what encoding is specified in certain environment variables. You can take
|
|
a look at :file:`test_i18n.py` and :file:`test_converters.py` to see tests
|
|
that attempt to cover enough input values to detect problems.
|
|
|
|
Since kitchen is currently supported on python-2.3.1+, it is desirable to test
|
|
kitchen on at least one python major version from python-2.3 through
|
|
python-2.7. We currently have access to a buildbot that has access to
|
|
python-2.4, python-2.6, and python-2.7. You can view it at
|
|
http://ci.csh.rit.edu:8080/view/Kitchen/ . The buildbot checks the devel
|
|
repository hourly and if new checkins have occurred, it attempts to rebuild.
|
|
If you need access to invoke builds on the buildbot more regularly than that,
|
|
contact Toshio to get access.
|
|
|
|
We were unable to get python-2.3 working in the buildbot so I manually run the
|
|
unittests on a CentOS-4 virtual machine (with python-2.3). I currently don't
|
|
test on python-2.5 but I'd be happy to take bug reports or get a new committer
|
|
that was interested in that platform.
|
|
|
|
Creating the release
|
|
====================
|
|
|
|
1. Make sure that any feature branches you want have been merged.
|
|
2. Pull in new translations and verify they are valid::
|
|
tx pull -a
|
|
# If msgfmt is installed, this will check that the catalogs are valid
|
|
./releaseutils.py
|
|
bzr commit -m 'Merge new translations from transifex.net'
|
|
3. Update the version in kitchen/__init__.py and NEWS.
|
|
4. Make a fresh clone of the repository::
|
|
cd $PATH_TO_MY_SHARED_REPO
|
|
bzr branch bzr://bzr.fedorahosted.org/bzr/kitchen/devel release
|
|
5. Make the source tarball in that directory::
|
|
cd release
|
|
python setup.py sdist
|
|
6. Make sure that the source tarball contains all of the files we want in the release::
|
|
cd ..
|
|
tar -xzvf release/dist/kitchen*tar.gz
|
|
diff -uNr devel kitchen-$RELEASE_VERSION
|
|
7. Upload the docs to pypi::
|
|
cd release
|
|
python setup.py upload_docs
|
|
8. Upload the tarball to pypi::
|
|
python setup.py sdist upload --sign
|
|
9. Upload the tarball to fedorahosted::
|
|
scp dist/kitchen*tar.gz fedorahosted.org:/srv/web/releases/k/i/kitchen/
|
|
10. Tag the release::
|
|
cd ../devel
|
|
bzr tag $RELEASE_VERSION
|
|
bzr push
|