HACKING.txt

Hacking on Bottlecap
====================

Here are some guidelines about hacking on Bottlecap.

Using a Development Checkout
----------------------------

Below is a quick start on creating a development environment using a Bottlecap
checkout.

- Create a new directory somewhere and ``cd`` to it::

  $ mkdir ~/hack-on-bottlecap
  $ cd ~/hack-on-bottlecap

- Check out a read-only copy of the Bottlecap source::

  $ git clone git://github.com/Pylons/bottlecap.git

  (alternately, create a writeable fork on GitHub and check that out).

- Create a virtualenv in which to install Bottlecap::

  $ virtualenv2.6 --no-site-packages env

- Install ``nose``, ``coverage``, and ``Sphinx`` into the virtualenv, to
  enable running the tests and building the docs::

  $ env/bin/easy_install nose coverage Sphinx

- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
  using git to do version control)::

  $ env/bin/easy_install setuptools-git

- Install each of the Bottlecap-related packages from the checkout into the
  virtualenv using ``setup.py develop`` (running ``setup.py develop``
  *must* be done while the current working directory is the ``bottlecap``
  checkout directory)::

  $ cd bottlecap_core
  $ ../env/bin/python setup.py develop
  $ cd ../bottlecap_grid
  $ ../env/bin/python setup.py develop
  $ cd ../bottlecap_livesearch
  $ ../env/bin/python setup.py develop
  $ cd ../bottlecap
  $ ../env/bin/python setup.py develop

- At that point, you should be able to run the Bottlecap WSGI application
  use ``paster serve``::

  $ cd ../env
  $ bin/paster serve --reload development.ini

Fixing Bugs
-----------

When fixing a bug in the Python code of one of the Bottlecap packages:

- Each bugfix should be accompanied by one or more new unit tests which
  exercise the bug (i.e., the new tests fail before applying the fix, and
  pass afterward).
  
- In some cases, it may be sufficient to extend existing tests (e.g., by
  adding assertions), as long as such tests fail before applying the real
  code change, and pass afterward.

Adding Features
---------------

In order to add a feature to one of the Bottlecap packages:

- The feature must be documented in both the API and narrative
  documentation (in ``docs/``).

- The feature must work fully on the following CPython versions:
  2.6, and 2.7 on both UNIX and Windows.

- The feature must not cause installation or runtime failure on Jython
  or App Engine.  If it doesn't cause installation or runtime failure,
  but doesn't actually *work* on these platforms, that caveat should be
  spelled out in the documentation.

- The feature must not add unnecessary dependencies (where
  "unnecessary" is of course subjective, but new dependencies should
  be discussed).

Coding Style
------------

- PEP8 compliance.  Whitespace rules are relaxed: not necessary to put
  2 newlines between classes.  But 80-column lines, in particular, are
  mandatory.

Test Coverage
-------------

- The codebase *must* have 100% test statement coverage after each
  commit.  You can test coverage via ``python setup.py nosetests
  --with-coverage`` (requires the ``nose`` and ``coverage`` packages).

Documentation Coverage
----------------------

- If you fix a bug, and the bug requires an API or behavior
  modification, all documentation in this package which references
  that API or behavior must change to reflect the bug fix, ideally in
  the same commit that fixes the bug or adds the feature.

Change Log
----------

- Feature additions and bugfixes must be added to the ``CHANGES.txt``
  file in the prevailing style.  Changelog entries should be long and
  descriptive, not cryptic.  Other developers should be able to know
  what your changelog entry means.

- Any changes which introduce backward-incompatible behavior changes
  **must** be documented as such, with a clear description of the changes
  which affected code must apply in order to work with the new version
  of the code.