---------
SVN usage
---------

All stages of :term:`FiPy` development are archived in a Subversion (SVN)
repository at MatForge_. You can browse through the code at
http://matforge.org/fipy/browser and, using an `SVN client`_, you can
download various tagged revisions of :term:`FiPy` depending on your needs. 

.. attention:: 

   Be sure to follow :ref:`INSTALLATION` to obtain all the prerequisites for
   :term:`FiPy`.
   
SVN client
==========

An ``svn`` client application is needed in order to fetch files from our
repository. This is provided on many operating systems (try executing
``which svn``) but needs to be installed on many others. The sources to
build Subversion, as well as links to various pre-built binaries for
different platforms, can be obtained from http://subversion.tigris.org.

SVN tags
========

In general, most users will not want to download the very latest state of
:term:`FiPy`, as these files are subject to active development and may not behave
as desired. Most users will not be interested in particular version numbers
either, but instead with the degree of code stability. Different "tracking
tags" are used to indicate different stages of :term:`FiPy` development. You will
need to decide on your own risk tolerance when deciding which stage of
development to track.

A fresh copy of :term:`FiPy` that is designated by a
particular ``<label>`` can be obtained with::

   $ svn checkout http://matforge.org/svn/fipy/<label>

An existing SVN checkout of FiPy can be shifted to a different state of
development by issuing the command::

   $ svn switch http://matforge.org/svn/fipy/<label> .

in the base directory of the working copy. The main tags (``<label>``)
for FiPy are:

``tags/version-x_y``
    designates a released version x.y. Any released
    version of FiPy will be designated with a fixed tag: The current
    version of FiPy is |version|.

``branches/version-x_y``
    designates a line of development based on a previously released version
    (i.e., if current development work is being spent on version 0.2, but a
    bug is found and fixed in version 0.1, that fix will be tagged as
    ``tags/version-0_1_1``, and can be obtained from the tip of
    ``branches/version-0_1``).

In addition:

``trunk``
    designates the latest revision of any file present in the
    repository.  FiPy is not guaranteed to pass its tests or to be in a
    consistent state when checked out under this tag.     

Any other tags will not generally be of interest to most users.

.. note::

   For some time now, we have done all significant development work on
   branches, only merged back to ``trunk`` when the tests pass
   successfully. Although we cannot guarantee that ``trunk`` will never be
   broken, you can always check our build status page 

       http://build.cmi.kent.edu:8010

   to find the most recent revision that it is running acceptably.


For those who are interested in learning more about Subversion, the
canonical manual is the `online Subversion Red Bean book`_ 
[SubversionRedBean]_.

.. _online Subversion Red Bean book: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://svnbook.red-bean.com

.. _MatForge: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://matforge.org/fipy