= Using Pidgin Mercurial =
The master copy of the source code for libpurple, Pidgin, Finch, http://pidgin.im/, and http://imfreedom.org/ resides in [http://mercurial.selenic.com/ Mercurial] repositories.

== Public Read-only Access ==
All Pidgin Mercurial repositories are available via HTTP from [http://hg.pidgin.im http://hg.pidgin.im].

== Read/Write Access for Developers/CPW's/SoC Students ==

=== 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 = 1

[defaults]
log = -v
}}}

=== Configure SSH for Access ===
Pidgin's Mercurial repositories are served by the [http://www.lshift.net/mercurial-server.html mercurial-server] package.  This relies entirely upon SSH key-based authentication, providing access control and a layer of accountability.

If you wish, you can simplify Mercurial ssh: URL's by adding the following to `~/.ssh/config`:
{{{
Host hg.pidgin.im
    Protocol 2
    User hg
}}}

=== SSH-based Push/Pull ===
You can get your initial checkouts from Mercurial by:
  * With SSH config above: `hg clone ssh://hg.pidgin.im/path/to/repo`
  * Without SSH config above: `hg clone ssh://hg@hg.pidgin.im/path/to/repo`

Once initial clones are done, pulls are a simple matter of running `hg pull` within your working copy.  You may optionally add `-u` to have your checkout automatically updated if possible.

Alternatively, you can clone the repository via http and add a `default-push` line to the `[paths]` section of the repository's `.hg/hgrc` file (you'll need to use the `hg@` prefix if you haven't set it via the SSH config):
{{{
default-push = ssh://hg.pidgin.im/path/to/repo
}}}

Pushes are a simple matter of `hg push` within your working copy.  If you need to push a new repository, you must clone:
  * With SSH config above: `hg clone . ssh://hg.pidgin.im/path/to/repo` in working copy
  * Without SSH config above: `hg clone . ssh://hg@hg.pidgin.im/path/to/repo` in working copy

== Administration ==

=== Access Control ===
Access control on Pidgin's Mercurial server is strict.  The repositories are structured like so (developers/CPW's listed here are for the purpose of example):

{{{
hg.pidgin.im          # Mercurial server
 + pidgin               # "Official" Pidgin and libpurple repositories
 |  + main                # replaced im.pidgin.pidgin in Monotone
 |  + 2_x_y               # replaced im.pidgin.pidgin.2.x.y in Monotone
 + dev                  # Developers' repositories
 |  + darkrain            # for all repositories darkrain wishes to create
 |  |  + irc                # replaced im.pidgin.cpw.darkrain42.irc in Monotone
 |  |  + xmpp_roster        # replaced im.pidgin.cpw.darkrain42.xppp.roster in Monotone
 |  + rekkanoryo          # for all repositories rekkanoryo wishes to create
 |     + examples           # replaced im.pidgin.cpw.rekkanoryo.examples in Monotone
 + cpw                  # Crazy Patch Writers' repositories
 |  + eionrobb            # for all repositories eionrobb wishes to create
 |     + newfeature          # new repository
 + www                  # For websites
 |  + pidgin              # for pidgin.im
 |  + imfreedom           # for imfreedom.org
 + soc                  # For Google Summer of Code projects (lines below should be obvious)
    + 2007
    |  + student1
    |     + project1
    + ...
    + 2012
       + studentx
          + projectx
}}}

Access control is as follows:
  * Developers have write access to `pidgin/*`
  * Developers can create and modify repositories in `dev/$NICKNAME/`
  * Crazy Patch Writers can create and modify repositories in `cpw/$NICKNAME/*`
  * Summer of Code students can create and modify repositories in `soc/$YEAR/$NICKNAME/*`
  * All of the above have read access to any repository on the server.
  * Those people with "root" access can do anything to any repository.  This access is strictly controlled.


=== Adding New Users ===
The process to allow new users SSH access to the Mercurial repositories is pretty simple, but requires someone with "root" access to mercurial-server.  Currently those people are datallah, rekkanoryo, and lschiere.

  1. Check out the `hgadmin` repo: `hg clone ssh://hg@hg.pidgin.im/hgadmin pidgin-hgadmin`
  1. `cd pidgin-hgadmin/keys`.  Inhere  is a series of directories.  The format is self-explaining.  Developers go in `devs/$NICKNAME`, CPW's in `cpws/$NICKNAME`, SoC students in `soc/$NICKNAME`.  This is to allow a single developer, CPW, or SoC student to have multiple SSH keys, perhaps for multiple machines.
  1. Create the appropriate directory.
  1. Within this directory create a file named for the SSH key being added, for example `user@somehost`.
  1. Put the SSH public key in this file.
  1. `hg add $FILE`
  1. Go back to the root of `pidgin-hgadmin`.
  1. Edit `access.conf`.  Copy an existing line for the same class of user (developer, CPW, SoC student) and modify it as appropriate for the new person's nickname and, if applicable, SoC year.
  1. `hg commit`
  1. `hg push` (mercurial-server updates automatically on push)

=== A Special Note About "root" Access ===
As indicated above, people who have "root" access to mercurial-server have the ability to configure the server via the `hgadmin` repo.  They also have the ability to bypass all ACL's, and thus can write to any repository, including developers', CPWs', and SoC students' repositories.

Additionally, there is a safety net built into the mercurial-server configuration.  In `/etc/mercurial-server` on rock.pidgin.im is a default ACL (`access.conf`) and a `keys` directory structure.  This default ACL is what grants "root" users their privileges, and the `keys` directory structure contains two keys in the `keys/root` directory.  These two keys belong to rekkanoryo and lschiere.  These keys are located here in the server's filesystem instead of in the hgadmin repository as a safety net.  When building the files used by mercurial-server, the tools ''always'' read from `/etc/mercurial-server` ''before'' reading from `hgadmin`; this allows rekkanoryo and lschiere to always be able to access the hgadmin repo in the event that it is damaged either through accidental or intentional means.  This safety net means that at least two people will ''always'' have access to our repositories.

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

=== Hooks ===
 * [http://hg.pidgin.im/util/hg_hooks/file/tip/pushlog.py 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
 * [http://hg.pidgin.im/util/hg_hooks/file/tip/author_email_hook.py 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
 * [http://hg.pidgin.im/util/hg_hooks/file/tip/notify_repo_sync.sh 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
  * Note: an initial manual pull may be necessary for new repos
 * [http://hg.pidgin.im/util/hg_hooks/file/tip/notify.py 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)
 * [http://hg.pidgin.im/util/hg_hooks/file/tip/hgcia.py 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 ===
 * [http://hg.pidgin.im/util/mozilla-pushlog/ pushlog extension] extension to expose pushlog information gathered by the hook to hgweb
 * [http://hg.pidgin.im/util/hg_templates/ hgweb templates] slightly tweaked vanilla templates to add pushlog