kitchen/HACKING
2015-10-08 09:26:18 -07:00

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