BUILDING AND INSTALLING
                    -----------------------

This document describes the steps needed to get the package built and
installed on CSC systems. If you don't have authority to do this, you
can safely skip it.

Building the Package
--------------------

To build a Debian package out of the sources, run `debuild` at the top
of the source tree. If all goes well, a Debian package and source tarball
will appear in the parent directory.

Do NOT build the package as root (rather, don't build anything as root in
general). Use 'fakeroot' so that the permissions in the .deb can be set
correctly. It is only necessary to build as root if you are using pbuilder,
which builds in a chroot.

You can examine the package with tools like dpkg-deb(1) and debdiff(1).
One useful command is `dpkg-deb -c <deb-file>`. This will give you a list
of files that will be installed.

If your build is a development build, you can safely delete it (it will
be overwritten anyway if a subsequent build has the same version number).
Otherwise copy it to a safe place.


Installing the Package
----------------------

So you have made your changes and have committed them to your repository, your
last test build was successful, and you're ready to install the package.

To install the package:

    1. Compare your debian/changelog with the changelog from the currently
       installed package. If your changelog has entries missing, find and
       merge them with git. This will ensure you do not overwrite others'
       changes.

       The changelog on caffeine is in "/usr/share/doc/csc/changelog.gz".

    2. Describe your changes in debian/changelog

        Run "dch -v new_version" and add bullets to describe all changes
        in the new version. Note that this format must be readable by
        dpkg-parsechangelog.

    4. Commit the changelog update to your repository

        You might want to mention that you are installing the package
        (i.e. it's a "release") in the commit message.

    5. Build the package

        Use 'debuild' to build the package.

    5. Install the package

        Run `dpkg -i csc_<version>_<arch>.deb`.

    6. Archive the package file and source

        You will be left with four files: a .deb, a .tar.gz, a .changes,
        and a .dsc. Save these to a safe place (preferably in /users/git
        so other can find them easily).

    7. Push to /users/git/public/pyceo.git

        This is a convenient hub for pushing/pulling between contributors.
        You must be in the 'git' group to do this - if you're able to install
        the package you will certainly be able to add yourself to this group.

If everyone follows these steps, every installed version will be a
descendant of the previous. Further, since old versions are archived it
will be easy to quickly get ceo working again after a bad update.