--- /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 <email@example.com>
+</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 <email@example.com>
+# 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>
