.. ############################################################################
   #    Copyright (C) 2011 - 2011 by Eike Welk                                #
   #    eike.welk@gmx.net                                                     #
   #                                                                          #
   #    License: GPL                                                          #
   #                                                                          #
   #    This program is free software; you can redistribute it and#or modify  #
   #    it under the terms of the GNU General Public License as published by  #
   #    the Free Software Foundation; either version 2 of the License, or     #
   #    (at your option) any later version.                                   #
   #                                                                          #
   #    This program is distributed in the hope that it will be useful,       #
   #    but WITHOUT ANY WARRANTY; without even the implied warranty of        #
   #    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         #
   #    GNU General Public License for more details.                          #
   #                                                                          #
   #    You should have received a copy of the GNU General Public License     #
   #    along with this program; if not, write to the                         #
   #    Free Software Foundation, Inc.,                                       #
   #    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             #
   ############################################################################

===============================================================================
Hacking and Contributing
===============================================================================

The program is currently developed on Linux (openSuse). I have only little 
knowledge of Windows and Mac OS, therefore developers from these platforms are
very welcome! 


Coding and Testing
================================================================================

The IDE **Eclipse** with its extension **Pydev** is used for coding, and 
debugging. The version control system **Bazaar** maintains the source code's 
history. **Launchpad** is used for code hosting and to organize the project. 
The development website is here:

    https://launchpad.net/jbidwatcher-companion

To get all development files type: ::

    bzr branch lp:jbidwatcher-companion

Testing is done with the **py.test** framework. All tests are in the file 
``test_ebstat.py``. To run the tests: change to the ``src/`` directory and type: ::

    py.test
    
The test framework will then (find and) run the tests. In case of any errors it
will create (overwhelmingly many) colored messages that point to the error. 
*py.test* is Unfortunately not integrated into Eclipse, therefore there are no
click-able error messages.

    - http://www.eclipse.org/
    - http://pydev.org/
    - http://bazaar.canonical.com/en/
    - http://pytest.org/


Documentation
================================================================================

The documentation is written with **reStructuredText** markup, and it is 
compiled with the documentation generator **Sphinx**. Documentation is here: 

    - http://sphinx.pocoo.org/index.html
    - http://docutils.sourceforge.net/docs/index.html (detailed reST documentation)


To create the whole website run the following command in directory ``doc/``: ::
       
    make html 

The directory ``doc/`` also contains a helper script, that generates the 
documentation and displays it in Firefox: ``test_wesite.sh``. It can be run
from **Vim** by typing: :: 

    !./test_wesite.sh


Releases
================================================================================

The ``src/`` directory contains an automated **release script**: 
``make_release.sh``. It creates the packages in which the program is 
distributed, and an archive of the website in the directory ``src/dist/``. It 
also tries to upload the packages to the *Python Package Index*. 
To make a release run: ::

    ./make_release.sh

Packages should be uploaded to Launchpad and to the Python Package Index.

    - https://launchpad.net/jbidwatcher-companion
    - http://pypi.python.org/pypi?%3Aaction=search&term=JBidwatcher-Companion


Bugs and Ideas
================================================================================

Bugs and feature requests (set importance to wishlist) can be reported with
JBidwatcher Companion's *bug tracker*: 

    https://bugs.launchpad.net/jbidwatcher-companion

Bigger ideas should be saved as *Blueprints* on Launchpad:

    https://blueprints.launchpad.net/jbidwatcher-companion