doc/reference/libpurple/code_contributions.xml

<?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>