=================================
Instructions for pyAMI Developers
=================================

.. Note::
    
    Use python 2.6 or later to build and develop pyAMI
    With CVMFS (on LXPLUS):

    export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
    source ${ATLAS_LOCAL_ROOT_BASE}/user/atlasLocalSetup.sh
    source ${ATLAS_LOCAL_ROOT_BASE}/packageSetups/atlasLocalPythonSetup.sh --pythonVersion=2.6.5-x86_64-slc5-gcc43

    The reason for this is that the sphinxcontrib-programoutput Sphinx extension
    requires at least Python 2.6:
    http://packages.python.org/sphinxcontrib-programoutput/

    pyAMI can still be deployed for Python 2.4, but developers will need at
    least Python 2.6


See the Makefile for common build/development tasks to make our lives easier.

To be sure that you are using the same versions of all pyAMI dependencies as the
other developers, before developing/testing pyAMI you should run::

    make bootstrap
    make buildout

or::

    make bs bo

To build lxml make sure the development packages of libxml2 and libxslt are
installed on your system (i.e. before running ``make buildout`` above).

You only need to run ``make boostrap`` once and you should only need to run
``make buildout`` if the version of a dependency changes. ``make buildout``
creates the development sandbox containing all of pyAMI's dependencies as well
as sphinx and its dependencies for building the docs.

While running ``make buildout`` you may see::

    SyntaxError: ('invalid syntax', ...

if you are using Python>=2.5 while the PyXML package is building. This is fine.
Don't be alarmed. This is a known issue with PyXML and fortunately it manages to
build and run properly for pyAMI.

Also ignore compiler warnings in lxml: src/lxml/lxml.etree.c. This is generated
C code.

After running ``make buildout`` you should see several new directories (be sure
to tell Subversion to ignore them!). ./bin contains the ami script as well as
scripts to generate the docs. ./bin also contains a python wrapper that puts
the local pyAMI sandbox in the sys.path. ./eggs contains eggs for pyAMI along
with sphinx and dependencies.

This is an isolated installation of pyAMI. To run the ami script::

    ./bin/ami -h

Using buildout allows us to develop pyAMI in a completely reproducible
environment. This environment can also be deployed to other machines with the
same architecture.


Running tests in the development sandbox
----------------------------------------

To run the pyAMI unit tests::

    make test

Add new tests to ./pyAMI/tests/test_ami.py. Before releasing a new tag all tests
there should pass.


Building the docs
-----------------

To build the docs::

    make docs

The generated html should now be in ./docs/_build/html/ 


Releasing a new version of pyAMI
--------------------------------

Increment the version in version.txt. Check that all unit tests (see above) pass
and that the docs build properly.

Be sure that any new non-python files that are not included by MANIFEST.in are
added there. MANIFEST.in controls what is and is not included in the source
tarball that is released on PyPI and the ATLAS Subversion repository.

Then follow the instructions below regarding updating pyAMI on PyPI, CERN AFS,
CVMFS, and the ATLAS Subversion repository.


Updating pyAMI on PyPI
----------------------

pyAMI is released on the Python Package Index (PyPI)::
    
    http://pypi.python.org/pypi/pyAMI/

To update the PyPI page of the current version or to post a
new version (you must be assigned a maintainer role for pyAMI on PyPI first)::

    python setup.py register --release

or::
    
    make register 

To upload a new tarball to PyPI::

    python setup.py sdist upload --release

or::

    make upload

If you upload a bad tarball you can delete it on PyPI after logging in and then
run the command above again.


Creating a self-contained bundle of pyAMI and its dependencies
--------------------------------------------------------------

To create a self-contained bundle::

    make bundle

This will create a tarball at ./dist/pyAMI-X.Y.Z-bundle.tar.gz containing pyAMI
and lxml (all other dependencies are already in pyAMI.extern).


Updating pyAMI on CVMFS
-----------------------

Send a new bundle (see above) tar.gz to Asoka De Silva <desilva@cern.ch> and
request that the version provided by CVMFS be updated.


Updating pyAMI on AFS
---------------------

Build a bundle (see above) and install this on AFS while on LXPLUS.

TODO: more instructions to come


Releasing a new verion of pyAMI in the ATLAS Subversion repository
------------------------------------------------------------------

Checkout pyAMI from ATLAS Subversion::

    svn co svn+ssh://${USER}@svn.cern.ch/reps/atlasoff/External/pyAMI/trunk pyAMI

Update the version number in cmt/pkgbuild_pyAMI.py::

    pkg_ver = 'X.Y.Z'

Check that pyAMI builds properly in CMT (after setting up Athena)::

    cd cmt/ && make

Commit and create the new tag::

    svn commit -m "version X.Y.Z"
    svn copy svn+ssh://${USER}@svn.cern.ch/reps/atlasoff/External/pyAMI/trunk \
    svn+ssh://${USER}@svn.cern.ch/reps/atlasoff/External/pyAMI/tags/pyAMI-XX-YY-ZZ


Create a source distribution
----------------------------

Follow the instructions above regarding the release of a new version and run::

    python setup.py sdist --release

or::
    
    make sdist

The new .tar.gz and .egg can now be found in dist/


Using git
---------

To clone the repository with git-svn::

    git svn clone https://lpsc.in2p3.fr/svn/AMI/ \
    --trunk=trunk/AMIWebServiceClient/pyAMI/ \
    --branches=branches/AMIWebServiceClient/pyAMI/branches/ \
    --tags=tags/AMIWebServiceClient/pyAMI/tags/ --prefix=svn/ pyAMI
