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> + All of the Pidgin related projects use + <ulink url="https://reviewboard.org">Review Board</ulink> for handling + <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>. + <sect2 id="first-time-setup"> + <title>First Time Setup</title> + 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> + <sect3 id="install-rbtools"> + <title>Install RBTools</title> + The recommended way to install RBTools is via pip and can be done with +pip3 install -U "RBTools>=1.0.3" + 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. + <sect3 id="configure-mercurial"> + <title>Mercurial Configuration</title> + 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>. + 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>. + 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. +username = Full Name <email@example.com> + 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. + 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 + 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. +wip = log --graph --rev wip + There are quite a few other useful configuration changes you can make, + and a few examples can be found below. +# update a large number of settings for a better user experience, highly +# make hg log show the graph as well as commit phase +lg = log --graph --template phases + Below is all of the above configuration settings to make it easier to +username = Full Name <email@example.com> +# update a large number of settings for a better user experience, highly +# 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 + <title>Log in to Review Board</title> + 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. + Once you have that account you can use it to login our Review Board + <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>. + Please note, you will have to login via the web interface before being + 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> + <title>Creating a New Review Request</title> + 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. + 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. + You can create the branch with the following command: +hg branch my-new-branch-name + 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. + <programlisting language="screen"> +Review request #403 posted. +https://reviews.imfreedom.org/r/403/ +https://reviews.imfreedom.org/r/403/diff/ + 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. + 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. + <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. + <title>Updating an Existing Review Request</title> + 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. + 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. + 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. + 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 + 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. + <title>Landing a Review Request</title> + 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. + 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 + 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>. + 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. + 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. + 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. + 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 + 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>. + 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. + <title>Testing Patches Locally</title> + 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. + 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. + 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 + <title>Cleaning up a Landed or Discarded Review Request</title> + 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 +hg prune -r 'branch(my-new-branch-name)' + 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. + You can repeat this for any other branches you need to clean up, and --- 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 @@
+ <part id="development"> + <title>Development</title> + <xi:include href="mercurial.xml" /> + <xi:include href="code_contributions.xml" /> --- /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> + 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. + 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. + In Distributed Version Control, <emphasis>cloning</emphasis> is the act + of acquiring a source repository. All of the Pidgin repositories are + <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. + 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. + <table label="Repository URLs"> + <entry>Description</entry> + <ulink url="https://keep.imfreedom.org/gplugin/gplugin"></ulink> + <entry>The plugin library used in Pidgin 3.</entry> + <ulink url="https://keep.imfreedom.org/libgnt/libgnt"></ulink> + <entry>The toolkit library used in Finch.</entry> + <ulink url="https://keep.imfreedom.org/pidgin/pidgin"></ulink> + The main pidgin repository that contains LibPurple, Pidgin, and + <ulink url="https://keep.imfreedom.org/talkatu/talkatu"></ulink> + <entry>The conversation widgets used in Pidgin 3.</entry> + You can see an example clone of Talkatu below but all of the repositories + will output a similar result. + <programlisting language="screen"> +$ hg clone https://keep.imfreedom.org/talkatu/talkatu +destination directory: talkatu +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 + <title>Keeping Your Clone Up to Date</title> + 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 + 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>. + Below is an example of updating Talkatu when it's already up to date. +pulling from https://keep.imfreedom.org/talkatu/talkatu + At this point you can review the code, build it, patch it, etc.