Overview

Installation

Client-side extension

This is the most common setup for this extension, being enabled on the client-side at the developer desk to allow him to indicate alongside with his changeset on which issue he is busy.

This is nothing fancier than enabling a general mercurial extension. No weird dependencies are needed, as the comunication with the database is done from the server-side.

After cloning the BugLink repository, the following lines have to be added to your user specific mercurial configuration file (Mercurial.ini on windows or .hgrc):

[extensions]
buglink = path/to/buglink/client/

Server-side extension

This one has to be enabled on each repository that may receive changesets from developpers. This extension will care about updating the database with the issue ID the developpers have been busy with. This can be a server-wide setting, a repository specific setting, or a setting reserved for the web instance of mercurial (hgweb.conf for instance).

This extension needs to talk to the database, and thus has dependency on SQLAlchemy.

As any other mercurial extensions, it is enabled through modification of the mercurial configuration file (Mercurial.ini on windows or .hgrc), where the following lines have to be added:

[extensions]
buglink_srv = path/to/buglink/server/

Web Interface

We are talking here about a WSGI application. there are plenty of guide on the internet on how to attach a WSGI application to your favorite web server. It looks like the last trendy one is to have a Gunicorn instance behind a nginx proxy. Apache and mod_wsgi also works fine.

The web interface has a bit more dependencies as the rest, as it needs to talk to the database, and deliver content for a web browser. The needed dependencies can be found in srv-requirements.txt. This file follows the pip requirements file format. So that within your virtualenv you just need to run:

pip -r srv-requirements.txt

The web app is located in the following file:

server/web.py

Usage

I will take for granted that you know how to handle a web browser, the server side-extension does not needs anything more than being enabled, we will also only discuss here the usage of the client-side extension.

This extension will record for each specified changeset an issue ID. Those are free-formed strings (without \n) locally stored within mercurial until they are pushed to the server and during the following pull operation the server aknowledge that they have been integrated to the database.

This information can be stored using different method:

During push

If you want to add an issue ID to all the pushed changeset together during your push operation, just use hg push --issueid, and the given issue ID will be linked to the pushed changesets and transmitted to the remote side.

During commit

You can also specify the issue that was worked on at commit-time, for this, you just have to use hg commit --issueid and the commited changeset will get a link with the specified issue ID.

At any other time

You can always use the command hg link or hg unlink to add or edit the issue IDs stored in the local cache.