About this software

ForgeHg is an extension for Allura [1] - an open source forge software written in Python. Being a "tool" in Allura's terminology, ForgeHg adds support for Mercurial distributed SCM [2]. 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.

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].

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.

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

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 pytest.

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:

pytest

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.