kitchen/docs/hacking.rst

=======================================
Conventions for contributing to kitchen
=======================================

-----
Style
-----

* Strive to be :pep:`8` compliant
* Run `:command:`pylint` ` over the code and try to resolve most of its nitpicking

------------------------
Python 2.3 compatibility
------------------------

At the moment, we're supporting python-2.3 and above.  Understand that there's
a lot of python features that we cannot use because of this.

Sometimes modules in the |stdlib|_ can be added to kitchen so that they're
available.  When we do that we need to be careful of several things:

1. Keep the module in sync with the version in the python-2.x trunk.  Use
   :file:`maintainers/sync-copied-files.py` for this.
2. Sync the unittests as well as the module.
3. Be aware that not all modules are written to remain compatible with
   Python-2.3 and might use python language features that were not present
   then (generator expressions, relative imports, decorators, with, try: with
   both except: and finally:, etc)  These are not good candidates for
   importing into kitchen as they require more work to keep synced.

---------
Unittests
---------

* At least smoketest your code (make sure a function will return expected
  values for one set of inputs).
* Note that even 100% coverage is not a guarantee of working code!  Good tests
  will realize that you need to also give multiple inputs that test the code
  paths of called functions that are outside of your code.  Example::

        def to_unicode(msg, encoding='utf8', errors='replace'):
            return unicode(msg, encoding, errors)

        # Smoketest only.  This will give 100% coverage for your code (it
        # tests all of the code inside of to_unicode) but it leaves a lot of
        # room for errors as it doesn't test all combinations of arguments
        # that are then passed to the unicode() function.

        tools.ok_(to_unicode('abc') == u'abc')

        # Better -- tests now cover non-ascii characters and that error conditions
        # occur properly.  There's a lot of other permutations that can be
        # added along these same lines.
        tools.ok_(to_unicode(u'café', 'utf8', 'replace'))
        tools.assert_raises(UnicodeError, to_unicode, [u'cafè ñunru'.encode('latin1')])

* We're using nose for unittesting.  Rather than depend on unittest2
  functionality, use the functions that nose provides.
* Remember to maintain python-2.3 compatibility even in unittests.

----------------------------
Docstrings and documentation
----------------------------

We use sphinx to build our documentation.  We use the sphinx autodoc extension
to pull docstrings out of the modules for API documentation.  This means that
docstrings for subpackages and modules should follow a certain pattern.  The
general structure is:

* Introductory material about a module in the module's top level docstring.

  * Introductory material should begin with a level two title: an overbar and
    underbar of '-'.

* docstrings for every function.

  * The first line is a short summary of what the function does
  * This is followed by a blank line
  * The next lines are a `field list
    <http://sphinx.pocoo.org/markup/desc.html#info-field-lists>_` giving
    information about the function's signature.  We use the keywords:
    ``arg``, ``kwarg``, ``raises``, ``returns``, and sometimes ``rtype``.  Use
    these to describe all arguments, key word arguments, exceptions raised,
    and return values using these.

    * Parameters that are ``kwarg`` should specify what their default
      behaviour is.

.. _kitchen-versioning:

------------------
Kitchen versioning
------------------

Currently the kitchen library is in early stages of development.  While we're
in this state, the main kitchen library uses the following pattern for version
information:

* Versions look like this::
    __version_info__ = ((0, 1, 2),)
    __version__ = '0.1.2'

* The Major version number remains at 0 until we decide to make the first 1.0
  release of kitchen.  At that point, we're declaring that we have some
  confidence that we won't need to break backwards compatibility for a while.
* The Minor version increments for any backwards incompatible API changes.
  When this is updated, we reset micro to zero.
* The Micro version increments for any other changes (backwards compatible API
  changes, pure bugfixes, etc).

.. note::

    Versioning is only updated for releases that generate sdists and new
    uploads to the download directory.  Usually we update the version
    information for the library just before release.  By contrast, we update
    kitchen :ref:`subpackage-versioning` when an API change is made.  When in
    doubt, look at the version information in the last release.

----
I18N
----

All strings that are used as feedback for users need to be translated.
:mod:`kitchen` sets up several functions for this.  :func:`_` is used for
marking things that are shown to users via print, GUIs, or other "standard"
methods.  Strings for exceptions are marked with :func:`b_`.  This function
returns a byte :class:`str` which is needed for use with exceptions::

    from kitchen import _, b_

    def print_message(msg, username):
        print _('%(user)s, your message of the day is:  %(message)s') % {
                'message': msg, 'user': username}

        raise Exception b_('Test message')

This serves several purposes:

* It marks the strings to be extracted by an xgettext-like program.
* :func:`_` is a function that will substitute available translations at
  runtime.

.. note::

    By using the ``%()s with dict`` style of string formatting, we make this
    string friendly to translators that may need to reorder the variables when
    they're translating the string.

`paver <http://www.blueskyonmars.com/projects/paver/>_` and `babel
<http://babel.edgewall.org/>_` are used to extract the strings.

-----------
API updates
-----------

Kitchen strives to have a long deprecation cycle so that people have time to
switch away from any APIs that we decide to discard.  Discarded APIs should
raise a :exc:`DeprecationWarning` and clearly state in the warning message and
the docstring how to convert old code to use the new interface.  An example of
deprecating a function::

    import warnings

    from kitchen import _
    from  kitchen.text.converters import to_bytes, to_unicode
    from kitchen.text.new_module import new_function

    def old_function(param):
        '''**Deprecated**

        This function is deprecated.  Use
        :func:`kitchen.text.new_module.new_function` instead. If you want
        unicode strngs as output, switch to::

            >>> from kitchen.text.new_module import new_function
            >>> output = new_function(param)

        If you want byte strings, use::

            >>> from kitchen.text.new_module import new_function
            >>> from kitchen.text.converters import to_bytes
            >>> output = to_bytes(new_function(param))
        '''
        warnings.warn(_('kitchen.text.old_function is deprecated.  Use'
            ' kitchen.text.new_module.new_function instead'),
            DeprecationWarning, stacklevel=2)

        as_unicode = isinstance(param, unicode)
        message = new_function(to_unicode(param))
        if not as_unicode:
            message = to_bytes(message)
        return message

If a particular API change is very intrusive, it may be better to create a new
version of the subpackage and ship both the old version and the new version.

---------
NEWS file
---------

Update the :file:`NEWS` file when you make a change that will be visible to
the users.  This is not a ChangeLog file so we don't need to list absolutely
everything but it should give the user an idea of how this version differs
from prior versions.  API changes should be listed here explicitly.  bugfixes
can be more general::

    -----
    0.2.0
    -----
    * Relicense to LGPLv2+
    * Add kitchen.text.format module with the following functions:
      textual_width, textual_width_chop.
    * Rename the kitchen.text.utils module to kitchen.text.misc.  use of the
      old names is deprecated but still available.
    * bugfixes applied to kitchen.pycompat24.defaultdict that fixes some
      tracebacks

-------------------
Kitchen subpackages
-------------------

Kitchen itself is a namespace.  The kitchen sdist (tarball) provides certain
useful subpackages.

.. seealso::

    `Kitchen addon packages`_
        For information about subpackages not distributed in the kitchen sdist
        that install into the kitchen namespace.

.. _subpackage-versioning:

Versioning
==========

Each subpackage should have its own version information which is independent
of the other kitchen subpackages and the main kitchen library version. This is
used so that code that depends on kitchen APIs can check the version
information.  The standard way to do this is to put something like this in the
subpackage's :file:`__init__.py`::

    from kitchen.versioning import version_tuple_to_string

    __version_info__ = ((1, 0, 0),)
    __version__ = version_tuple_to_string(__version_info__)

:attr:`__version_info__` is documented in :mod:`kitchen.versioning`.  The
values of the first tuple should describe API changes to the module.  There
are at least three numbers present in the tuple: (Major, minor, micro).  The
major version number is for backwards incompatible changes (For
instance, removing a function, or adding a new mandatory argument to
a function).  Whenever one of these occurs, you should increment the major
number and reset minor and micro to zero.  The second number is the minor
version.  Anytime new but backwards compatible changes are introduced this
number should be incremented and the micro version number reset to zero.  The
micro version should be incremented when a change is made that does not change
the API at all.  This is a common case for bugfixes, for instance.

Version information beyond the first three parts of the first tuple may be
useful for versioning but semantically have similar meaning to the micro
version.

.. note::

    We update the :attr:`__version_info__` tuple when the API is updated.
    This way there's less chance of forgetting to update the API version when
    a new release is made.  However, we try to only increment the version
    numbers a single step for any release.  So if kitchen-0.1.0 has
    kitchen.text.__version__ == '1.0.1', kitchen-0.1.1 should have
    kitchen.text.__version__ == '1.0.2' or '1.1.0' or '2.0.0'.

Criteria for subpackages in kitchen
===================================

Supackages within kitchen should meet these criteria:

* Generally useful or needed for other pieces of kitchen.

* No mandatory requirements outside of the |stdlib|_.

  * Optional requirements from outside the |stdlib|_ are allowed.  Things with
    mandatory requirements are better placed in `kitchen addon packages`_

* Somewhat API stable -- this is not a hard requirement.  We can change the
  kitchen api.  However, it is better not to as people may come to depend on
  it.

  .. seealso::

    `API Updates`_

----------------------
Kitchen addon packages
----------------------

Addon packages are very similar to subpackages integrated into the kitchen
sdist.  This section just lists some of the differences to watch out for.

setup.py
========

Your :file:`setup.py` should contain entries like this::

    # It's suggested to use a dotted name like this so the package is easily
    # findable on pypi:
    setup(name='kitchen.config',
        # Include kitchen in the keywords, again, for searching on pypi
        keywords=['kitchen', 'configuration'],
        # This package lives in the directory kitchen/config
        packages=['kitchen.config'],
        # [...]
    )

Package directory layout
========================

Create a :file:`kitchen` directory in the toplevel.  Place the addon
subpackage in there.  For example::

  ./                     <== toplevel with README, setup.py, NEWS, etc
  kitchen/
  kitchen/__init__.py
  kitchen/config/        <== subpackage directory
  kitchen/config/__init__.py

Fake kitchen module
===================

The :file::`__init__.py` in the :file:`kitchen` directory is special.  It
won't be installed.  It just needs to pull in the kitchen from the system so
that you are able to test your module.  You should be able to use this
boilerplate::

    # Fake module.  This is not installed,  It's just made to import the real
    # kitchen modules for testing this module
    import pkgutil

    # Extend the __path__ with everything in the real kitchen module
    __path__ = pkgutil.extend_path(__path__, __name__)

.. note::

    :mod:`kitchen` needs to be findable by python for this to work.  Installed
    in the :file:`site-packages` directory or adding it to the
    :envvar:`PYTHONPATH` will work.

Your unittests should now be able to find both your submodule and the main
kitchen module.

Versioning
==========

It is recommended that addon packages version similarly to
:ref:`subpackage-versioning`.  The :data:`__version_info__` and
:data:`__version__` strings can be changed independently of  the version
exposed by setup.py so that you have both an API version
(:data:`__version_info__`) and release version that's easier for people to
parse.  However, you aren't required to do this and you could follow
a different methodology if you want (for instance, :ref:`kitchen-versioning`)