This page is out of date. Please see the updated version at https://pidgin.im/development/contributing/mercurial/

Using Pidgin Mercurial

The master copy of the source code for libpurple, Pidgin, Finch, https://pidgin.im/, and ​https://imfreedom.org/ resides in ​Mercurial repositories.

All public Pidgin Mercurial repositories are available via HTTP/HTTPS from ​bitbucket.

Clone the Repository and Select a Branch

To start working with Pidgin from Mercurial, you'll probably want to clone our main repository:

hg clone https://bitbucket.org/pidgin/main pidgin

This will give you a pidgin directory with the 3.0.0 development code by default. If you want to develop against Pidgin 3.0.0, you're all set!

Naturally, Pidgin has a number of branches within its repository, and these branches handle various projects including our maintenance of Pidgin 2.x.y. We won't go into all the branches here, as there are a lot of them, but we know some people would like to work against Pidgin 2.x.y instead of 3.0.0. In order to do that, clone the repository as above, but then do this:

cd pidgin
hg up release-2.x.y

You now have a Pidgin 2 tree to work with. Happy hacking!

Configure Mercurial

Mercurial is configured through serveral rc files. You can override the system-wide settings on a per-user or per-repository basis by changing either ~/.hgrc or <repository>/.hg/hgrc. See man hgrc for details.

You must set your username when working with Pidgin's Mercurial repositories. To do that, add two lines to ~/.hgrc (or optionally <repository>/.hg/hgrc, if you want to use a different username for other Mercurial repositories):

[ui]
username = First Last <email@address.tld>

Other useful options that can be set in the [ui] section of an hgrc are the merge tool and to make Mercurial verbose or not:

[ui]
username = First Last <email@address.tld>
verbose = True
merge = meld

Git diffs can be useful too, and making hg log -v the default behavior for hg log can be helpful:

[diff]
git = True

[defaults]
log = -v

How the email and CIA notification works

[This may be a bit out-of-date after the move to Bitbucket.]

As detailed below, we use slightly modified versions of the notify and hgcia hooks that are distributed with hg. They are modified in order to support notification for multiple repositories without triggering duplicate notifications as the same revisions are pushed between various repositories on the server.

The way it works is that there is a special repository that isn't served publicly (/srv/mercurial-server/notification-repo/) which is used to trigger the notifications as new revisions are enter it. A hook is set up for the hg user and mercurial-server ('changegroup.notify_sync' - see below) so that revisions pushed into any repository will automatically be pulled into the notification repo. This can be disabled on a per repository basis by overriding and disabling the hook in the appropriate repository-specific .hg/hgrc file:

[hooks]
changegroup.notify_sync =

In order to trigger notifications for a new repository that is not related (has no shared history) to any repository that has already been synced to the notification repo (e.g. the first time that the repository containing the pidgin website was synced to the notification repo), an initial manual pull must be made with the --force parameter specified:

/srv/mercurial-server/repos/util/hg_hooks/notify_repo_sync.sh /absolute/path/to/new/repo --force

In order to avoid triggering notifications for revisions that aren't already in the notification repo (e.g. when the pidgin.im website was converted from mtn to hg), the hooks can be disabled as the relevant revisions are pulled into the notification repo. Note, this should only be done when notifications have already been sent out for these revisions in some other way.

hg --cwd /srv/mercurial-server/notification-repo pull /path/to/source/repo \
    --config hooks.changegroup.cia= \
    --config hooks.incoming.notify= \
    --config hooks.changegroup.pushlog= \
    --config hooks.pretxnchangegroup.authorcheck= \
    --config hooks.changegroup.notify_sync=  

Hooks / Extensions

There are a number of hooks, extensions and other configuration in place for the various repositories:

Hooks

• ​pushlog.py tweaked version of a mozilla hook to keep track of who pushed a particular revision
  • This is registered globally as 'changelog.pushlog' for both the hg user and mercurial-server
• ​author_email_hook.py verify that incoming commit authors are in the form of an email address - 'user@domain.tld' or 'User Name <user@domain.tld>'
  • This is registered globally as 'pretxnchangegroup.authorcheck' for both the hg user and mercurial-server
• ​notify_repo_sync.sh trigger a sync in the background with the notification repo to trigger email and cia notifications
  • This is registered globally as 'changegroup.notify_sync' for both the hg user and mercurial-server
• ​notify.py slightly tweaked version of the built-in hg hook to facilitate using a separate repo for driving the notifications
  • This is registered in the /srv/mercurial-server/notification-repo/ (which isn't served anywhere)
• ​hgcia.py slightly tweaked version of the built-in hg hook for CIA bot notification
  • This is registered in the /srv/mercurial-server/notification-repo/ (which isn't served anywhere)

hgweb stuff

• ​pushlog extension extension to expose pushlog information gathered by the hook to hgweb
• ​hgweb templates slightly tweaked vanilla templates to add pushlog