= Using Pidgin Mercurial =
This page is intended to house documentation for using Pidgin's Mercurial repositories once we switch from Monotone to Mercurial.

== Background ==
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.

== Anonymous Pull (Non-Developers) ==
All Pidgin Mercurial repositories will be available via HTTP.  As we are not yet using Mercurial, this is not yet available.

== Developers ==

=== Configure SSH For Access (Developers/CPW's/SoC Students Only) ===
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.

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 will be 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                # replaces im.pidgin.pidgin in Monotone
 |  + 2_x_y               # replaces im.pidgin.pidgin.2.x.y in Monotone
 + dev                  # Developers' repositories
 |  + darkrain            # for all repositories darkrain wishes to create
 |  |  + irc                # replaces im.pidgin.cpw.darkrain42.irc in Monotone
 |  |  + xmpp_roster        # replaces im.pidgin.cpw.darkrain42.xppp.roster in Monotone
 |  + rekkanoryo          # for all repositories rekkanoryo wishes to create
 |     + examples           # replaces 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 will be 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 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`.
    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)