Version 19 (modified by 11 years ago) (diff) | ,
---|
Using Pidgin Mercurial
The master copy of the source code for libpurple, Pidgin, Finch, http://pidgin.im/, and http://imfreedom.org/ resides in Mercurial repositories.
Public Read-only Access
All Pidgin Mercurial repositories are available via HTTP from http://hg.pidgin.im.
hg clone http://hg.pidgin.im/pidgin/main pidgin-main
Read/Write Access for Developers/CPWs/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 = True [defaults] log = -v
Configure SSH for Access
Pidgin's Mercurial repositories are served by the 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: URLs 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 using the Public Read-only Access instructions.
The configuration of the server is such that pushes can only be performed via SSH, so you'll want to 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):
[paths] default-push = ssh://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 use hg pull -u
to have your checkout automatically updated if possible.
Alternatively, you can clone the repository via ssh using the URI in the default-push
settings above if http access is problematic for some reason
Pushes to existing repositories are a simple matter of hg push
within your working copy.
Creating a new repository on the server must be done using hg clone
:
hg clone . ssh://hg.pidgin.im/path/to/repo
in working copy- (you'll need to use the
hg@
prefix if you haven't set it via the SSH config)
- (you'll need to use the
Administration
Access Control
Access control on Pidgin's Mercurial server is such that all developers can write to our master repositories, but each developer and CPW has their own repositories that anyone can read but only they can write to. The repositories are structured like so (developers/CPWs listed here are for the purpose of example):
hg.pidgin.im # Mercurial server + pidgin # "Official" Pidgin and libpurple repositories | + main # replaced im.pidgin.pidgin, 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 and CPWs 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/*
- Public Read-only access is available for 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, markdoliner, rekkanoryo, elb, and lschiere.
- Check out the
hgadmin
repo:hg clone ssh://hg@hg.pidgin.im/hgadmin pidgin-hgadmin
cd pidgin-hgadmin/keys
. In here is a series of directories. The format is self-explaining. Developers go indevs/$NICKNAME
, CPWs incpws/$NICKNAME
, SoC students insoc/$NICKNAME
. This is to allow a single developer, CPW, or SoC student to have multiple SSH keys, perhaps for multiple machines.- Create the appropriate directory.
- Within this directory create a file named for the SSH key being added, for example
user@somehost
. - Put the SSH public key in this file.
hg add $FILE
- Go back to the root of
pidgin-hgadmin
. - 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. hg commit
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 ACLs, 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 the relevant keys in the keys/root
directory. 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 access to 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.
How the email and CIA notification works
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 thehg
user and mercurial-server
- This is registered globally as
- 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 thehg
user and mercurial-server
- This is registered globally as
- 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 thehg
user and mercurial-server
- This is registered globally as
- 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)
- This is registered in the
- 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)
- This is registered in the
hgweb stuff
- pushlog extension extension to expose pushlog information gathered by the hook to hgweb
- hgweb templates slightly tweaked vanilla templates to add pushlog