kitchen/HACKING.rst

216 lines
7.4 KiB
ReStructuredText
Raw Normal View History

2015-10-08 16:26:18 +00:00
================================
Some notes on hacking on kitchen
================================
:Author: Toshio Kuratomi
2016-07-08 23:18:01 +00:00
:Maintainer: Ralph Bean
:Date: 2 Dec 2014
:Version: 1.2.x
2015-10-08 16:26:18 +00:00
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
2016-07-08 23:18:01 +00:00
extract the messages. Run the following from the top level directory::
2015-10-08 16:26:18 +00:00
2016-07-08 23:18:01 +00:00
pybabel extract -o po/kitchen.pot kitchen2 kitchen3
2015-10-08 16:26:18 +00:00
Then commit this pot file and upload to transifex::
tx push -s
2016-07-08 23:18:01 +00:00
git commit -m 'Extract new strings from the source files' po/kitchen.pot
git push
2015-10-08 16:26:18 +00:00
To pull messages from transifex prior to making a release, do::
tx pull -a
2016-07-08 23:18:01 +00:00
git commit -m 'Merge new translations from transifex' po/*.po
2015-10-08 16:26:18 +00:00
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::
2016-07-08 23:18:01 +00:00
git add po/fr.po
git commit -m 'New French translation' po/fr.po
2015-10-08 16:26:18 +00:00
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::
2016-07-08 23:18:01 +00:00
./runtests.sh
2015-10-08 16:26:18 +00:00
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.
2016-07-08 23:18:01 +00:00
Since kitchen is currently supported on python2 and python3, it is desirable to
run tests against as many python versions as possible. We currently have a
jenkins instance in the Fedora Infrastructure private cloud with a job set up
for kitchen at http://jenkins.cloud.fedoraproject.org/job/kitchen/
2015-10-08 16:26:18 +00:00
2016-07-08 23:18:01 +00:00
It is not currently running tests against python-2.{3,4,5,6}. If you are
interested in getting those builds running automatically, please speak up in
the #fedora-apps channel on freenode.
2015-10-08 16:26:18 +00:00
Creating the release
====================
2016-07-08 23:18:01 +00:00
Then commit this pot file and upload to transifex:
2015-10-08 16:26:18 +00:00
1. Make sure that any feature branches you want have been merged.
2016-07-08 23:18:01 +00:00
2. Make a fresh branch for your release::
git flow release start $VERSION
3. Extract strings for translation and push them to transifex::
pybabel extract -o po/kitchen.pot kitchen2 kitchen3
tx push -s
git commit -m 'Extract new strings from the source files' po/kitchen.pot
git push
4. Wait for translations. In the meantime...
5. Update the version in ``kitchen/__init__.py`` and ``NEWS.rst``.
6. When they're all ready, pull in new translations and verify they are valid::
2015-10-08 16:26:18 +00:00
tx pull -a
# If msgfmt is installed, this will check that the catalogs are valid
./releaseutils.py
2016-07-08 23:18:01 +00:00
git commit -m 'Merge new translations from transifex.net'
git push
7. Create a pull-request so someone else from #fedora-apps can review::
hub pull-request -b master
8. Once someone has given it a +1, then make a source tarball::
2015-10-08 16:26:18 +00:00
python setup.py sdist
2016-07-08 23:18:01 +00:00
9. Upload the docs to pypi::
mkdir -p build/sphinx/html
sphinx-build kitchen2/docs/ build/sphinx/html
2015-10-08 16:26:18 +00:00
python setup.py upload_docs
2016-07-08 23:18:01 +00:00
10. Upload the tarball to pypi::
python setup.py sdist upload --sign
11. Upload the tarball to fedorahosted::
scp dist/kitchen*tar.gz* fedorahosted.org:/srv/web/releases/k/i/kitchen/
12. Tag and bag it::
git flow release finish -m $VERSION -u $YOUR_GPG_KEY_ID $VERSION
git push origin develop:develop
git push origin master:master
git push origin --tags
# Your pull-request should automatically close. Double-check this, though.