pidgin/pidgin

7a4e48594a24
Parents 206563c8b5c6
Children beb4c413afe8
Update all of the development documentation

Add documentation for using our repos and how to contribute to them.

Testing Done:
Built the docs locally and verified they look decent.

Reviewed at https://reviews.imfreedom.org/r/404/
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference/libpurple/code_contributions.xml Mon Jan 18 23:07:50 2021 -0600
@@ -0,0 +1,459 @@
+<?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-code-contributions">
+ <title>Code Contributions</title>
+
+ <sect2 id="introduction">
+ <title>Introduction</title>
+ <para>
+ All of the Pidgin related projects use
+ <ulink url="https://reviewboard.org">Review Board</ulink> for handling
+ contributions at
+ <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="first-time-setup">
+ <title>First Time Setup</title>
+ <para>
+ There are a few things you'll need to set up to be able to submit a code
+ review to these projects. This includes installing
+ <ulink url="https://www.reviewboard.org/downloads/rbtools/">RBTools</ulink>
+ as well as some additional
+ <ulink url="https://www.mercurial-scm.org/">Mercurial</ulink>
+ configuration.
+ </para>
+
+ <sect3 id="install-rbtools">
+ <title>Install RBTools</title>
+
+ <para>
+ The recommended way to install RBTools is via pip and can be done with
+ the following command.
+ </para>
+
+ <programlisting>
+pip3 install -U "RBTools>=1.0.3"
+</programlisting>
+
+ <para>
+ Once RBTools is installed you need to make sure that <code>rbt</code>
+ is available on your <code>$PATH</code>. To do this, you may need to
+ add <code>$HOME/.local/bin</code> to your <code>$PATH</code>. The exact
+ procedure to do this is dependent on your setup and outside of the
+ scope of this document.
+ </para>
+ </sect3>
+
+ <sect3 id="configure-mercurial">
+ <title>Mercurial Configuration</title>
+
+ <para>
+ This configuration for Mercurial is to make your life as a contributor
+ easier. There a few different ways to configure Mercurial, but these
+ instructions will update your user specific configuration in
+ <code>$HOME/.hgrc</code>.
+ </para>
+
+ <para>
+ The first thing we need to do is to install the evolve extension. This
+ extension makes rewriting history safe and we use it extensively in our
+ repositories. You can install it with a simple <code>pip3 install -U
+ hg-evolve</code>. We will enable it below with some other bundled
+ extensions, but you can find more information about it
+ <ulink url="https://www.mercurial-scm.org/wiki/EvolveExtension">here</ulink>.
+ </para>
+
+ <para>
+ When working with Mercurial repositories it is very important to make
+ sure that your username is set properly as it is added to every commit
+ you make. To set your username you must add it to the <code>[ui]</code>
+ section in your <code>$HOME/.hgrc</code> like the following example.
+ </para>
+
+ <programlisting>
+[ui]
+username = Full Name &lt;email@example.com&gt;
+</programlisting>
+
+ <para>
+ Next we need to make sure that the <emphasis>evolve</emphasis>
+ and <emphasis>rebase</emphasis> extensions are loaded. To do so add the
+ lines in the following example. You do not need to put anything after
+ the <code>=</code> as this will tell Mercurial to look for them in the
+ default places for extensions.
+ </para>
+
+ <programlisting>
+[extensions]
+evolve =
+rebase =
+</programlisting>
+
+ <para>
+ Next we're going to create a <emphasis>revsetalias</emphasis>. This will
+ be used to make it easier to look at your history and submit your review
+ request.
+ </para>
+
+ <programlisting>
+[revsetalias]
+wip = only(.,default)
+</programlisting>
+
+ <para>
+ This alias will show us just the commits that are on our working branch
+ and not on the default branch. The default branch is where all
+ accepted code contributions go. Optionally, you can add the
+ <code>wip</code> command alias below which will show you the revision
+ history of what you are working on.
+ </para>
+
+ <programlisting>
+[alias]
+wip = log --graph --rev wip
+</programlisting>
+
+ <para>
+ There are quite a few other useful configuration changes you can make,
+ and a few examples can be found below.
+ </para>
+
+ <programlisting>
+[ui]
+# update a large number of settings for a better user experience, highly
+# recommended!!
+tweakdefaults = true
+
+[alias]
+# make hg log show the graph as well as commit phase
+lg = log --graph --template phases
+</programlisting>
+
+ <para>
+ Below is all of the above configuration settings to make it easier to
+ copy/paste.
+ </para>
+
+ <programlisting>
+[ui]
+username = Full Name &lt;email@example.com&gt;
+# update a large number of settings for a better user experience, highly
+# recommended!!
+tweakdefaults = true
+
+[extensions]
+evolve =
+rebase =
+
+[alias]
+# make hg log show the graph as well as commit phase
+lg = log --graph --template phases
+
+# show everything between the upstream and your wip
+wip = log --graph --rev wip
+
+[revsetalias]
+wip = only(.,default)
+</programlisting>
+ </sect3>
+
+ <sect3 id="login">
+ <title>Log in to Review Board</title>
+
+ <para>
+ To be able to submit a review request you need to have an account on
+ our JetBrains Hub instance at
+ <ulink url="https://hub.imfreedom.org">hub.imfreedom.org</ulink>. You
+ can create an account here in a number of ways and even turn on two
+ factor authentication. But please note that if you turn on two factor
+ authentication you will need to create an application password to be
+ able to login to Review Board.
+ </para>
+
+ <para>
+ Once you have that account you can use it to login our Review Board
+ instance at
+ <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>.
+ Please note, you will have to login via the web interface before being
+ able to use RBTools.
+ </para>
+
+ <para>
+ Once you have an account and have logged into our Review Board site, you
+ can begin using RBTools. In your shell, navigate to a Mercurial clone of
+ one of the Pidgin or purple-related projects, then run the
+ <code>rbt login</code> command. You should only need to do this once,
+ unless you change your password or have run the <code>rbt logout</code>
+ command.
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="create">
+ <title>Creating a New Review Request</title>
+
+ <para>
+ Before starting a new review request, you should make sure that your
+ local copy of the repository is up to date. To do so, make sure you are
+ on the <emphasis>default</emphasis> branch via
+ <code>hg update default</code>. Once you are on the
+ <emphasis>default</emphasis> branch, you can update your copy with
+ <code>hg pull --update</code>. Now that you're starting with the most
+ recent code, you can proceed with your contributions.
+ </para>
+
+ <para>
+ While it's not mandatory, it is highly recommended that you work on your
+ contributions via a branch. If you don't go this path, you will have
+ issues after your review request is merged. This branch name can be
+ whatever you like as it will not end up in the main repositories, and
+ you can delete it from your local repository after it is merged. See
+ <link linkend="cleanup">cleanup</link> for more information.
+ </para>
+
+ <para>
+ You can create the branch with the following command:
+ </para>
+
+ <programlisting>
+hg branch my-new-branch-name
+</programlisting>
+
+ <para>
+ Now that you have a branch started, you can go ahead and work like you
+ normally would, committing your code at logical times, etc. Once you
+ have some work committed and you are ready to create a new review
+ request, you can type <code>rbt post wip</code> and you should be good to
+ go. This will create a new review request using all of the committed work
+ in your repository and will output something like below.
+ </para>
+
+ <programlisting language="screen">
+Review request #403 posted.
+
+https://reviews.imfreedom.org/r/403/
+https://reviews.imfreedom.org/r/403/diff/
+</programlisting>
+
+ <para>
+ At this point, your review request has been posted, but it is not yet
+ published. This means no one can review it yet. To do that, you need to
+ go to the URL that was output from your <code>rbt post</code> command
+ and verify that everything looks correct. If this review request fixes
+ any bugs, please make sure to enter their numbers in the bugs field on
+ the right. Also, be sure to review the actual diff yourself to make sure
+ it includes what you intended it to and nothing extra.
+ </para>
+
+ <para>
+ Once you are happy with the review request, you can hit the publish
+ button which will make the review request public and alert the reviewers
+ of its creation. Optionally you can pass <code>--open</code> to
+ <code>rbt post</code> in the future to automatically open the draft
+ review in your web browser.
+ </para>
+
+ <para>
+ <code>rbt post</code> has a ton of options, so be sure to check them out
+ with <code>rbt post --help</code>. There are even options to
+ automatically fill out the bugs fixed fields among other things.
+ </para>
+ </sect2>
+
+ <sect2 id="update">
+ <title>Updating an Existing Review Request</title>
+
+ <para>
+ Typically with a code review, you're going to need to make some updates.
+ However there's also a good chance that your original branching point
+ has changed as other contributions are accepted. To deal with this you'll
+ need to rebase your branch on top of the new changes.
+ </para>
+
+ <para>
+ Rebasing, as the name suggests is the act of replaying your previous
+ commits on top of a new base revision. Mercurial makes this pretty easy.
+ First, make sure you are on your branch with
+ <code>hg up my-branch-name</code>. Now you can preview the rebase with
+ <code>hg rebase -d default --keepbranches --dry-run</code>. We prefer
+ doing a dry-run just to make sure there aren't any major surprises. You
+ may run into some conflicts, but those will have to be fixed regardless.
+ </para>
+
+ <para>
+ If everything looks good, you can run the actual rebase with
+ <code>hg rebase -d default --keepbranches</code>. Again if you run into
+ any conflicts, you will have to resolve them and they will cause the
+ dry-run to fail. Once you have fixed the merge conflicts, you'll then
+ need to mark the files as resolved with
+ <code>hg resolve --mark filename</code>. When you have resolved all of
+ the conflicted files you can continue the rebase with
+ <code>hg rebase --continue</code>. You may run into multiple conflicts,
+ so just repeat until you're done.
+ </para>
+
+ <para>
+ After rebasing you can start addressing the comments in your review and
+ commit them. Once they are committed, you can update your existing
+ review request with <code>rbt post --update</code>. If for some reason
+ <code>rbt</code> can not figure out the proper review request to
+ update, you can pass the number in via
+ <code>rbt post --review-request-id #</code>. Note that when using
+ <code>--review-request-id</code> you no longer need to specify
+ <code>--update</code>.
+ </para>
+
+ <para>
+ Just like an initial <code>rbt post</code>, the updated version will be
+ in a draft state until you publish it. So again, you'll need to visit the
+ URL that was output, verify everything, and click the publish button.
+ </para>
+ </sect2>
+
+ <sect2 id="land">
+ <title>Landing a Review Request</title>
+
+ <para>
+ This will typically only be done by the Pidgin developers with push
+ access. If you want to test a patch from a review request, please see the
+ <link linkend="patch">patch</link> section below.
+ </para>
+
+ <para>
+ It is <emphasis>HIGHLY</emphasis> recommended that you use a separate
+ clone of the repository in question when you want to land review requests.
+ This makes it much easier to avoid accidentally pushing development work
+ to the canonical repository which makes everyone's life easier. Also, the
+ mainline repositories now auto publish, so if you do not selectively push
+ commits, all of your draft commits will be published. You can name this
+ additional clone whatever you like, but using something like
+ <code>pidgin-clean</code> is a fairly common practice. This makes it easy
+ for you to know that this clone is only meant for landing review requests,
+ and other admistrative work like updating the ChangeLog and COPYRIGHT
+ files.
+ </para>
+
+ <para>
+ When you are ready to land a review request you need to make sure you are
+ on the proper branch. In most cases this will be the branch named
+ <emphasis>default</emphasis> and can be verified by running the command
+ <code>hg branch</code>. Next you need to make sure that your local copy
+ is up to date. You can do this by running <code>hg pull --update</code>.
+ </para>
+
+ <para>
+ Please note, if you run <code>hg pull</code> and then immediately run
+ <code>hg pull --update</code> you will <emphasis>not</emphasis> update to
+ the most recent commit as this new invocation of <code>hg pull</code> has
+ not actually pulled in any new commits. To properly update, you'll need
+ to run <code>hg update</code> instead.
+ </para>
+
+ <para>
+ Once your local copy is up to date you can land the review request with
+ <code>rbt land --no-push --review-request-id #</code> where <code>#</code>
+ is the number of the review request you are landing. The
+ <code>--no-push</code> argument is to disable pushing this commit
+ immediately. Most of our configuration already enables this flag for you,
+ but if you're in doubt, please use the <code>--no-push</code> argument.
+ </para>
+
+ <para>
+ Once the review request has been landed, make sure to verify that the
+ revision history looks correct, run a test build as well as the unit
+ tests, and if everything looks good, you can continue with the
+ housekeeping before we finally push the new commits.
+ </para>
+
+ <para>
+ The housekeeping we need to do entails a few things. If this is a big new
+ feature or bug fix, we should be documenting this in the ChangeLog file
+ for the repository. Please follow the existing convention of mentioning
+ the contributor as well as the issues addressed and the review request
+ number. Likewise, if this is someone's first contribution you will need
+ to add them to the COPYRIGHT file in the repository as well. If you had
+ to update either of these files, review your changes and commit them
+ directly.
+ </para>
+
+ <para>
+ Now that any updates to ChangeLog and COPYRIGHT are completed, we can
+ actually start pushing the changes back to the canonical repository.
+ Currently not all of the canonical repositories are publishing
+ repositories so we'll need to manually mark the commits as public. This
+ is easily accomplished with <code>hg phase --public</code>.
+ <emphasis>Note</emphasis>, if you are not using a separate clone of the
+ canonical repository you will need to specify a revision to avoid
+ publishing every commit in your repository. If you run into issues or
+ have more questions about phases see the
+ <ulink url="https://www.mercurial-scm.org/wiki/Phases">official documentation</ulink>.
+ </para>
+
+ <para>
+ Now that the changes have been made public, we can finally push to the
+ canonical repository with <code>hg push</code>. Once that is done, you'll
+ also need to go and mark the review request as
+ <emphasis>Submitted</emphasis> in the Review Board web interface.
+ </para>
+ </sect2>
+
+ <sect2 id="patch">
+ <title>Testing Patches Locally</title>
+
+ <para>
+ If you want to test a patch locally for any reason, you first need to
+ make sure that you are on the target branch for the review request which
+ is listed on the review request page. In most cases this will be the
+ <emphasis>default</emphasis> branch. Regardless you'll need to run
+ <code>hg up branch-name</code> before applying the patch.
+ </para>
+
+ <para>
+ Now that you are on the correct branch, you can apply the patch with
+ <code>rbt patch #</code> where <code>#</code> is the id of the review
+ request you want to test. This will apply the patch from the review
+ request to your working copy without committing it.
+ </para>
+
+ <para>
+ Once you're done with your testing you can remove the changes with
+ <code>hg revert --no-backup --all</code>. This will return your
+ repository to exactly what it was before the patch was applied. The
+ <code>--no-backup</code> argument says to not save the changes that you
+ are reverting and the <code>--all</code> argument tells Mercurial to
+ revert all files.
+ </para>
+ </sect2>
+
+ <sect2 id="cleanup">
+ <title>Cleaning up a Landed or Discarded Review Request</title>
+
+ <para>
+ Whether or not your pull request has been accepted, you probably want to
+ clean it up from your local repository. To do so, you need to update to
+ a branch other than the branch you built it on. In the following example,
+ we're going to remove the branch named
+ <emphasis>my-new-branch-name</emphasis> that we used to create a review
+ request.
+ </para>
+
+ <programlisting>
+hg up default
+hg prune -r 'branch(my-new-branch-name)'
+</programlisting>
+
+ <para>
+ Now, all commits that were on the <emphasis>my-new-branch-name</emphasis>
+ branch will have their contents removed but interally Mercurial keeps
+ track that these revisions have been deleted.
+ </para>
+
+ <para>
+ You can repeat this for any other branches you need to clean up, and
+ you're done!
+ </para>
+ </sect2>
+</chapter>
--- a/doc/reference/libpurple/libpurple-docs.xml Mon Jan 18 18:00:51 2021 -0600
+++ b/doc/reference/libpurple/libpurple-docs.xml Mon Jan 18 23:07:50 2021 -0600
@@ -18,6 +18,13 @@
</abstract>
</bookinfo>
+ <part id="development">
+ <title>Development</title>
+
+ <xi:include href="mercurial.xml" />
+ <xi:include href="code_contributions.xml" />
+ </part>
+
<part id="tutorial">
<title>Tutorials</title>
--- /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 &lt;URL&gt;</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>