--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference/libpurple/mercurial.xml Mon Jan 18 23:07:50 2021 -0600
@@ -0,0 +1,144 @@
+<?xml version='1.0' encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter id="chapter-using-mercurial">
+ <title>Using Pidgin Mercurial</title>
+
+ <sect2 id="introduction">
+ <title>Introduction</title>
+
+ <para>
+ These instructions will help you clone a copy of any of the Pidgin
+ related <ulink url="https://mercurial-scm.org">Mercurial</ulink>
+ repositories and keep them up to date.
+ </para>
+
+ <note>
+ These instructions are just for cloning/updating the Pidgin repositories.
+ If you're looking for documentation on contributing code, please see the
+ <link linkend="chapter-code-contributions">Code Contributions</link>
+ page after you have successfully cloned the repository from this page.
+ </note>
+ </sect2>
+
+ <sect2 id="cloning">
+ <title>Cloning</title>
+
+ <para>
+ In Distributed Version Control, <emphasis>cloning</emphasis> is the act
+ of acquiring a source repository. All of the Pidgin repositories are
+ hosted in Mercurial at
+ <ulink url="https://keep.imfreedom.org/">keep.imfreedom.org</ulink>. To
+ clone them you will be using the command
+ <code>hg clone <URL></code>. The specific URL can be looked up in
+ the table below depending what you are trying to clone.
+ </para>
+
+ <note>
+ If you are trying build Pidgin 3, you can just clone that repository and
+ the build system will automatically clone the other repositories for you.
+ </note>
+
+ <table label="Repository URLs">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>URL</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GPlugin</entry>
+ <entry>
+ <ulink url="https://keep.imfreedom.org/gplugin/gplugin"></ulink>
+ </entry>
+ <entry>The plugin library used in Pidgin 3.</entry>
+ </row>
+ <row>
+ <entry>LibGNT</entry>
+ <entry>
+ <ulink url="https://keep.imfreedom.org/libgnt/libgnt"></ulink>
+ </entry>
+ <entry>The toolkit library used in Finch.</entry>
+ </row>
+ <row>
+ <entry>Pidgin</entry>
+ <entry>
+ <ulink url="https://keep.imfreedom.org/pidgin/pidgin"></ulink>
+ </entry>
+ <entry>
+ The main pidgin repository that contains LibPurple, Pidgin, and
+ Finch.
+ </entry>
+ </row>
+ <row>
+ <entry>Talkatu</entry>
+ <entry>
+ <ulink url="https://keep.imfreedom.org/talkatu/talkatu"></ulink>
+ </entry>
+ <entry>The conversation widgets used in Pidgin 3.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ You can see an example clone of Talkatu below but all of the repositories
+ will output a similar result.
+ </para>
+
+ <programlisting language="screen">
+$ hg clone https://keep.imfreedom.org/talkatu/talkatu
+destination directory: talkatu
+requesting all changes
+adding changesets
+adding manifests
+adding file changes
+added 348 changesets with 1074 changes to 268 files
+new changesets 0feed1461a4a:f0fda4aace2d
+updating to branch default
+109 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</programlisting>
+ </sect2>
+
+ <sect2 id="updating">
+ <title>Keeping Your Clone Up to Date</title>
+
+ <para>
+ If you are just tracking Pidgin development and are not contributing,
+ chances are you are still on the <emphasis>default</emphasis> branch. But
+ let's make sure, and run <code>hg update default</code>. This will change
+ to the <emphasis>default</emphasis> branch if you're not currently on it
+ or do nothing.
+ </para>
+
+ <para>
+ Now that you are on the <emphasis>default</emphasis> branch, you can
+ simply run <code>hg pull --update</code> to pull in all new changes and
+ update your local copy. Please note, if you accidentally run
+ <code>hg pull</code>, that is without the update, a subsequent
+ <code>hg pull --update</code> will not update to the latest revisions as
+ this invocation of <code>hg pull</code> did not find any new revisions. To
+ properly update in this scenario, you'll need to run
+ <code>hg update</code>.
+ </para>
+
+ <para>
+ Below is an example of updating Talkatu when it's already up to date.
+ </para>
+
+ <programlisting>
+$ hg pull --update
+pulling from https://keep.imfreedom.org/talkatu/talkatu
+searching for changes
+no changes found
+</programlisting>
+
+ <para>
+ At this point you can review the code, build it, patch it, etc.
+ </para>
+ </sect2>
+</chapter>
