diff options
Diffstat (limited to 'doc/reference/libpurple/code_contributions.md')
-rw-r--r-- | doc/reference/libpurple/code_contributions.md | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/doc/reference/libpurple/code_contributions.md b/doc/reference/libpurple/code_contributions.md new file mode 100644 index 0000000000..dc2fc48e3e --- /dev/null +++ b/doc/reference/libpurple/code_contributions.md @@ -0,0 +1,330 @@ +Title: Code Contributions +Slug: code-contributions + +## Code Contributions + +### Introduction + +All of the Pidgin related projects use [Review +Board](https://reviewboard.org/) for handling contributions at +[reviews.imfreedom.org](https://reviews.imfreedom.org). + +### First Time Setup + +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 +[RBTools](https://www.reviewboard.org/downloads/rbtools/) +as well as some additional +[Mercurial](https://www.mercurial-scm.org/) +configuration. + +#### Install RBTools + +The recommended way to install RBTools is via pip and can be done with the +following command. + +```sh +pip3 install -U "RBTools>=1.0.3" +``` +Once RBTools is installed you need to make sure that `rbt` is available on your +`$PATH`. To do this, you may need to add `$HOME/.local/bin` to your `$PATH`. +The exact procedure to do this is dependent on your setup and outside of the +scope of this document. + +#### Mercurial Configuration + +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 `$HOME/.hgrc`. + +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 `pip3 install -U hg-evolve`. We +will enable it below with some other bundled extensions, but you can find more +information about it +[here](https://www.mercurial-scm.org/wiki/EvolveExtension). + +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 `[ui]` section in your `$HOME/.hgrc` like +the following example. + +```ini +[ui] +username = Full Name <email@example.com> +``` + +Next we need to make sure that the ***evolve*** and ***rebase*** extensions are +loaded. To do so add the lines in the following example. You do not need to put +anything after the `=` as this will tell Mercurial to look for them in the +default places for extensions. + +```ini +[extensions] +evolve = +rebase = +``` + +Next we're going to create a ***revsetalias***. This will be used to make it +easier to look at your history and submit your review request. + +```ini +[revsetalias] +wip = only(.,default) +``` + +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 `wip` command alias below which +will show you the revision history of what you are working on. + +```ini +[alias] +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. + +```ini +[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 +``` + +Below is all of the above configuration settings to make it easier to +copy/paste. + +```ini +[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) +``` + +#### Log in to Review Board + +To be able to submit a review request you need to have an account on our +JetBrains Hub instance at [hub.imfreedom.org](https://hub.imfreedom.org). 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](https://www.jetbrains.com/help/hub/application-passwords.html) to be +able to login to Review Board. + +Once you have that account you can use it to login our Review Board instance at +[reviews.imfreedom.org](https://reviews.imfreedom.org). Please note, you will +have to login via the web interface before being able to use RBTools. + +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 `rbt login` command. You should +only need to do this once, unless you change your password or have run the `rbt +logout` command. + +### Creating a New Review Request + +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 ***default*** branch via +`hg update default`. Once you are on the +***default*** branch, you can update your copy with +`hg pull --update`. 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 +[cleanup](#cleanup) for more information. + +You can create the branch with the following command: + +```sh +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 `rbt +post wip` 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. + +```sh +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 `rbt post` 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 `--open` to `rbt post` in the future to +automatically open the draft review in your web browser. + +`rbt post` has a ton of options, so be sure to check them out with `rbt post +--help`. There are even options to automatically fill out the bugs fixed fields +among other things. + +### Updating an Existing Review Request + +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 +`hg up my-branch-name`. Now you can preview the rebase with +`hg rebase -d default --keepbranches --dry-run`. 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 `hg rebase -d +default --keepbranches`. 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 `hg +resolve --mark filename`. When you have resolved all of the conflicted files +you can continue the rebase with `hg rebase --continue`. 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 `rbt post --update`. If for some reason `rbt` can not figure out the +proper review request to update, you can pass the number in via `rbt post +--review-request-id #`. Note that when using `--review-request-id` you no +longer need to specify `--update`. + +Just like an initial `rbt post`, 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. + +### Landing a Review Request + +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 [patch](#path) +section below. + +It is ***HIGHLY*** 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 `pidgin-clean` 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. + +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 ***default*** +and can be verified by running the command `hg branch`. Next you need to make +sure that your local copy is up to date. You can do this by running `hg pull +--update`. + +Please note, if you run `hg pull` and then immediately run `hg pull --update` +you will ***not*** update to the most recent commit as this new invocation of +`hg pull` has not actually pulled in any new commits. To properly update, +you'll need to run `hg update` instead. + +Once your local copy is up to date you can land the review request with `rbt +land --no-push --review-request-id #` where `#` is the number of the review +request you are landing. The `--no-push` 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 `--no-push` 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 directly. + +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 `hg phase +--public`. ***Note***, 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 [official documentation](https://www.mercurial-scm.org/wiki/Phases). + +Now that the changes have been made public, we can finally push to the +canonical repository with `hg push`. Once that is done, you'll also need to go +and mark the review request as ***Submitted*** in the Review Board web +interface. + +### Testing Patches Locally + +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 ***default*** branch. +Regardless you'll need to run `hg up branch-name` before applying the patch. + +Now that you are on the correct branch, you can apply the patch with +`rbt patch #` where `#` 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 `hg revert +--no-backup --all`. This will return your repository to exactly what it was +before the patch was applied. The `--no-backup` argument says to not save the +changes that you are reverting and the `--all` argument tells Mercurial to +revert all files. + +### Cleaning up a Landed of Discarded Review Request + +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 ***my-new-branch-name*** that we used to create a +review request. + +```sh +hg up default +hg prune -r 'branch(my-new-branch-name)' +``` + +Now, all commits that were on the ***my-new-branch-name*** branch will have +their contents removed but internally Mercurial keeps track that these revisions +have been deleted. + +You can repeat this for any other branches you need to clean up, and you're +done! + |