Read Me
++++++++++++++
ForgeHg README
++++++++++++++
About this software
===================
ForgeHg is a Web Server Gateway Interface [1]_ application that acts as
extension for Allura [2]_ - an open source forge software written in Python.
Being a "tool" in Allura's terminology, ForgeHg adds support for Mercurial
distributed SCM [3]_. After proper installing and configuring in Allura
project, it becomes possible to add and delete Mercurial repositories at will,
to browse their branches, histories, source trees, commits - with diffs - and
more.
.. [1] http://www.wsgi.org/
.. [2] http://sourceforge.net/p/allura
.. [3] http://mercurial.selenic.com/
About this file
===============
This README contains basic information about ForgeHg, it's installation and
usage. It uses reStructuredText (reST) [4]_, a plain file format that retains
readability while enabling rendering of properly formatted content to more
complex formats, such as HTML or PDF. You may encounter some peculiarities,
i.e. an underscore ( _ ) after reference brackets or a double colon ( :: )
before literal block. These are reST features and should be ignored.
For futher documentation, please refer to general Allura docs [2]_.
.. [4] http://docutils.sourceforge.net/rst.html
Download
========
ForgeHG is being developed in a git repository. Newest version can be obtained
by cloning the repository to your directory of choice. First install git [5]_
from sources or from prebuilt packages available for your operating system.
Then execute following command in a target directory::
git clone git://git.code.sf.net/p/forgehg/code ForgeHg
This will create a catalog named ``ForgeHg`` with most recent copy of
repository's content. A PyPI [6]_ release is underway.
.. [5] http://git-scm.com/
.. [6] http://pypi.python.org/
Installation
============
To install ForgeHg, you need a working installation of Allura. If you've
faithfully followed Allura's installation instructions, you should have a
virtual Python environment created with virtualenv [7]_ . Activate it before
installing ForgeHg.
If you've downloaded a prebuilt package, you can easily use ``pip`` or
``easy_install`` tools that are added by default to your virtualenv, i.e.::
easy_install ForgeHg-0.1.tar.gz
Alternatively, you can unpack the package (it's a standard archive anyways),
navigate to unpacked directory and issue:
python setup.py install
You may also want to install from copied repository (as described in `Download`_
section above), for example if you want to execute test suite (see `Testing`_,
below) or if you're interested in a particular feature that hasn't made it to
release yet. You can do that with exactly same command as above, but it's useful
to tag ForgeHg's version with date, so that distutils will correctly determine
your installation as older than future release in case you'll want to upgrade.
This can be achieved with ``egg_info -d`` option:
python setup.py egg_info -d install
.. [7] http://www.virtualenv.org/
Usage
=====
After proper installation, Mercurial support should appear in available tools'
list in Allura's project admin view. Installing it in a project is no different
from other tools: simply click on the icon to bring a short configuration form.
Form's fields refer to:
- **Label** - how Mercurial repository browser will be labeled in project's top
navigation bar,
- **Mount Point** - at what URL path should it appear.
To visit repository browser, click newly-created icon under the label you've
typed in the form. There you'll see some quickstart information on working with
Mercurial, and when you'll do an initial commit, repository browser will take
it's place. On the left are links to commit browser, forking the repository,
tags and branches when you create them.
ForgeHg can be futher configured in project's admin tools view. From there you
can define viewable files' extensions, refresh repository, define permissions,
change tool's label or delete it completely from project's configuration.
Testing
=======
If you've installed ForgeHg from cloned source code repository, as described in
the `Installation`_ section above, you are able to execute an enclosed test
suite. Tests examine ForgeHg's code routines in a controlled, isolated manner,
ensuring its' flawless operation on your system setup. To make use of tests, you
must install nose [8]_ extension to standard Python unittest framework.
Both ForgeHg and Allura use PasteDeploy [9]_ as a mean to configure application
at startup. PasteDeploy reads configuration from INI files, and testing
configuration is by convention stored in ``test.ini`` files. You should find
it in the same directory as this README. The format should be familiar to you,
but in case it's not, it is fully documented on PasteDeploy website. What's
important here is that ForgeHg re-uses some sections from Allura's
``test.ini``, so you need to put a valid path to it in place of default. The
paths can be found at ``use`` keys in sections starting with ``app:``.
Once that's done, make sure ``test.ini`` directory is set as your current
working directory, and from it execute command::
nosetests
The test suite will be started, outputting one character for each test case:
``.`` (dot) for success, ``F`` for failure and ``E`` for error.
.. [8] http://packages.python.org/nose
.. [9] http://pythonpaste.org/deploy/
Licensing
=========
ForgeHg is distributed under the terms of GNU General Public License version 2.
Full text of the license should be enclosed to your copy in the LICENSE file
residing in the same directory as this README. If there is no such file, please
report this at ``dev@allura.apache.org`` mailing list.
Dave Brondsema
Cory Johns
Rick Copeland
Peter Hartmann
Igor Bondarenko