comparison: doc/reference/libpurple/code_contributions.xml
doc/reference/libpurple/code_contributions.xml
- changeset 40716
- 7a4e48594a24
- child 40972
- af05c99a4702
equal
deleted
inserted
replaced
| 40715:206563c8b5c6 | 40716:7a4e48594a24 |
|---|---|
| 1 <?xml version='1.0' encoding="UTF-8"?> | |
| 2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
| 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ | |
| 4 ]> | |
| 5 <chapter id="chapter-code-contributions"> | |
| 6 <title>Code Contributions</title> | |
| 7 | |
| 8 <sect2 id="introduction"> | |
| 9 <title>Introduction</title> | |
| 10 <para> | |
| 11 All of the Pidgin related projects use | |
| 12 <ulink url="https://reviewboard.org">Review Board</ulink> for handling | |
| 13 contributions at | |
| 14 <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>. | |
| 15 </para> | |
| 16 </sect2> | |
| 17 | |
| 18 <sect2 id="first-time-setup"> | |
| 19 <title>First Time Setup</title> | |
| 20 <para> | |
| 21 There are a few things you'll need to set up to be able to submit a code | |
| 22 review to these projects. This includes installing | |
| 23 <ulink url="https://www.reviewboard.org/downloads/rbtools/">RBTools</ulink> | |
| 24 as well as some additional | |
| 25 <ulink url="https://www.mercurial-scm.org/">Mercurial</ulink> | |
| 26 configuration. | |
| 27 </para> | |
| 28 | |
| 29 <sect3 id="install-rbtools"> | |
| 30 <title>Install RBTools</title> | |
| 31 | |
| 32 <para> | |
| 33 The recommended way to install RBTools is via pip and can be done with | |
| 34 the following command. | |
| 35 </para> | |
| 36 | |
| 37 <programlisting> | |
| 38 pip3 install -U "RBTools>=1.0.3" | |
| 39 </programlisting> | |
| 40 | |
| 41 <para> | |
| 42 Once RBTools is installed you need to make sure that <code>rbt</code> | |
| 43 is available on your <code>$PATH</code>. To do this, you may need to | |
| 44 add <code>$HOME/.local/bin</code> to your <code>$PATH</code>. The exact | |
| 45 procedure to do this is dependent on your setup and outside of the | |
| 46 scope of this document. | |
| 47 </para> | |
| 48 </sect3> | |
| 49 | |
| 50 <sect3 id="configure-mercurial"> | |
| 51 <title>Mercurial Configuration</title> | |
| 52 | |
| 53 <para> | |
| 54 This configuration for Mercurial is to make your life as a contributor | |
| 55 easier. There a few different ways to configure Mercurial, but these | |
| 56 instructions will update your user specific configuration in | |
| 57 <code>$HOME/.hgrc</code>. | |
| 58 </para> | |
| 59 | |
| 60 <para> | |
| 61 The first thing we need to do is to install the evolve extension. This | |
| 62 extension makes rewriting history safe and we use it extensively in our | |
| 63 repositories. You can install it with a simple <code>pip3 install -U | |
| 64 hg-evolve</code>. We will enable it below with some other bundled | |
| 65 extensions, but you can find more information about it | |
| 66 <ulink url="https://www.mercurial-scm.org/wiki/EvolveExtension">here</ulink>. | |
| 67 </para> | |
| 68 | |
| 69 <para> | |
| 70 When working with Mercurial repositories it is very important to make | |
| 71 sure that your username is set properly as it is added to every commit | |
| 72 you make. To set your username you must add it to the <code>[ui]</code> | |
| 73 section in your <code>$HOME/.hgrc</code> like the following example. | |
| 74 </para> | |
| 75 | |
| 76 <programlisting> | |
| 77 [ui] | |
| 78 username = Full Name <email@example.com> | |
| 79 </programlisting> | |
| 80 | |
| 81 <para> | |
| 82 Next we need to make sure that the <emphasis>evolve</emphasis> | |
| 83 and <emphasis>rebase</emphasis> extensions are loaded. To do so add the | |
| 84 lines in the following example. You do not need to put anything after | |
| 85 the <code>=</code> as this will tell Mercurial to look for them in the | |
| 86 default places for extensions. | |
| 87 </para> | |
| 88 | |
| 89 <programlisting> | |
| 90 [extensions] | |
| 91 evolve = | |
| 92 rebase = | |
| 93 </programlisting> | |
| 94 | |
| 95 <para> | |
| 96 Next we're going to create a <emphasis>revsetalias</emphasis>. This will | |
| 97 be used to make it easier to look at your history and submit your review | |
| 98 request. | |
| 99 </para> | |
| 100 | |
| 101 <programlisting> | |
| 102 [revsetalias] | |
| 103 wip = only(.,default) | |
| 104 </programlisting> | |
| 105 | |
| 106 <para> | |
| 107 This alias will show us just the commits that are on our working branch | |
| 108 and not on the default branch. The default branch is where all | |
| 109 accepted code contributions go. Optionally, you can add the | |
| 110 <code>wip</code> command alias below which will show you the revision | |
| 111 history of what you are working on. | |
| 112 </para> | |
| 113 | |
| 114 <programlisting> | |
| 115 [alias] | |
| 116 wip = log --graph --rev wip | |
| 117 </programlisting> | |
| 118 | |
| 119 <para> | |
| 120 There are quite a few other useful configuration changes you can make, | |
| 121 and a few examples can be found below. | |
| 122 </para> | |
| 123 | |
| 124 <programlisting> | |
| 125 [ui] | |
| 126 # update a large number of settings for a better user experience, highly | |
| 127 # recommended!! | |
| 128 tweakdefaults = true | |
| 129 | |
| 130 [alias] | |
| 131 # make hg log show the graph as well as commit phase | |
| 132 lg = log --graph --template phases | |
| 133 </programlisting> | |
| 134 | |
| 135 <para> | |
| 136 Below is all of the above configuration settings to make it easier to | |
| 137 copy/paste. | |
| 138 </para> | |
| 139 | |
| 140 <programlisting> | |
| 141 [ui] | |
| 142 username = Full Name <email@example.com> | |
| 143 # update a large number of settings for a better user experience, highly | |
| 144 # recommended!! | |
| 145 tweakdefaults = true | |
| 146 | |
| 147 [extensions] | |
| 148 evolve = | |
| 149 rebase = | |
| 150 | |
| 151 [alias] | |
| 152 # make hg log show the graph as well as commit phase | |
| 153 lg = log --graph --template phases | |
| 154 | |
| 155 # show everything between the upstream and your wip | |
| 156 wip = log --graph --rev wip | |
| 157 | |
| 158 [revsetalias] | |
| 159 wip = only(.,default) | |
| 160 </programlisting> | |
| 161 </sect3> | |
| 162 | |
| 163 <sect3 id="login"> | |
| 164 <title>Log in to Review Board</title> | |
| 165 | |
| 166 <para> | |
| 167 To be able to submit a review request you need to have an account on | |
| 168 our JetBrains Hub instance at | |
| 169 <ulink url="https://hub.imfreedom.org">hub.imfreedom.org</ulink>. You | |
| 170 can create an account here in a number of ways and even turn on two | |
| 171 factor authentication. But please note that if you turn on two factor | |
| 172 authentication you will need to create an application password to be | |
| 173 able to login to Review Board. | |
| 174 </para> | |
| 175 | |
| 176 <para> | |
| 177 Once you have that account you can use it to login our Review Board | |
| 178 instance at | |
| 179 <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>. | |
| 180 Please note, you will have to login via the web interface before being | |
| 181 able to use RBTools. | |
| 182 </para> | |
| 183 | |
| 184 <para> | |
| 185 Once you have an account and have logged into our Review Board site, you | |
| 186 can begin using RBTools. In your shell, navigate to a Mercurial clone of | |
| 187 one of the Pidgin or purple-related projects, then run the | |
| 188 <code>rbt login</code> command. You should only need to do this once, | |
| 189 unless you change your password or have run the <code>rbt logout</code> | |
| 190 command. | |
| 191 </para> | |
| 192 </sect3> | |
| 193 </sect2> | |
| 194 | |
| 195 <sect2 id="create"> | |
| 196 <title>Creating a New Review Request</title> | |
| 197 | |
| 198 <para> | |
| 199 Before starting a new review request, you should make sure that your | |
| 200 local copy of the repository is up to date. To do so, make sure you are | |
| 201 on the <emphasis>default</emphasis> branch via | |
| 202 <code>hg update default</code>. Once you are on the | |
| 203 <emphasis>default</emphasis> branch, you can update your copy with | |
| 204 <code>hg pull --update</code>. Now that you're starting with the most | |
| 205 recent code, you can proceed with your contributions. | |
| 206 </para> | |
| 207 | |
| 208 <para> | |
| 209 While it's not mandatory, it is highly recommended that you work on your | |
| 210 contributions via a branch. If you don't go this path, you will have | |
| 211 issues after your review request is merged. This branch name can be | |
| 212 whatever you like as it will not end up in the main repositories, and | |
| 213 you can delete it from your local repository after it is merged. See | |
| 214 <link linkend="cleanup">cleanup</link> for more information. | |
| 215 </para> | |
| 216 | |
| 217 <para> | |
| 218 You can create the branch with the following command: | |
| 219 </para> | |
| 220 | |
| 221 <programlisting> | |
| 222 hg branch my-new-branch-name | |
| 223 </programlisting> | |
| 224 | |
| 225 <para> | |
| 226 Now that you have a branch started, you can go ahead and work like you | |
| 227 normally would, committing your code at logical times, etc. Once you | |
| 228 have some work committed and you are ready to create a new review | |
| 229 request, you can type <code>rbt post wip</code> and you should be good to | |
| 230 go. This will create a new review request using all of the committed work | |
| 231 in your repository and will output something like below. | |
| 232 </para> | |
| 233 | |
| 234 <programlisting language="screen"> | |
| 235 Review request #403 posted. | |
| 236 | |
| 237 https://reviews.imfreedom.org/r/403/ | |
| 238 https://reviews.imfreedom.org/r/403/diff/ | |
| 239 </programlisting> | |
| 240 | |
| 241 <para> | |
| 242 At this point, your review request has been posted, but it is not yet | |
| 243 published. This means no one can review it yet. To do that, you need to | |
| 244 go to the URL that was output from your <code>rbt post</code> command | |
| 245 and verify that everything looks correct. If this review request fixes | |
| 246 any bugs, please make sure to enter their numbers in the bugs field on | |
| 247 the right. Also, be sure to review the actual diff yourself to make sure | |
| 248 it includes what you intended it to and nothing extra. | |
| 249 </para> | |
| 250 | |
| 251 <para> | |
| 252 Once you are happy with the review request, you can hit the publish | |
| 253 button which will make the review request public and alert the reviewers | |
| 254 of its creation. Optionally you can pass <code>--open</code> to | |
| 255 <code>rbt post</code> in the future to automatically open the draft | |
| 256 review in your web browser. | |
| 257 </para> | |
| 258 | |
| 259 <para> | |
| 260 <code>rbt post</code> has a ton of options, so be sure to check them out | |
| 261 with <code>rbt post --help</code>. There are even options to | |
| 262 automatically fill out the bugs fixed fields among other things. | |
| 263 </para> | |
| 264 </sect2> | |
| 265 | |
| 266 <sect2 id="update"> | |
| 267 <title>Updating an Existing Review Request</title> | |
| 268 | |
| 269 <para> | |
| 270 Typically with a code review, you're going to need to make some updates. | |
| 271 However there's also a good chance that your original branching point | |
| 272 has changed as other contributions are accepted. To deal with this you'll | |
| 273 need to rebase your branch on top of the new changes. | |
| 274 </para> | |
| 275 | |
| 276 <para> | |
| 277 Rebasing, as the name suggests is the act of replaying your previous | |
| 278 commits on top of a new base revision. Mercurial makes this pretty easy. | |
| 279 First, make sure you are on your branch with | |
| 280 <code>hg up my-branch-name</code>. Now you can preview the rebase with | |
| 281 <code>hg rebase -d default --keepbranches --dry-run</code>. We prefer | |
| 282 doing a dry-run just to make sure there aren't any major surprises. You | |
| 283 may run into some conflicts, but those will have to be fixed regardless. | |
| 284 </para> | |
| 285 | |
| 286 <para> | |
| 287 If everything looks good, you can run the actual rebase with | |
| 288 <code>hg rebase -d default --keepbranches</code>. Again if you run into | |
| 289 any conflicts, you will have to resolve them and they will cause the | |
| 290 dry-run to fail. Once you have fixed the merge conflicts, you'll then | |
| 291 need to mark the files as resolved with | |
| 292 <code>hg resolve --mark filename</code>. When you have resolved all of | |
| 293 the conflicted files you can continue the rebase with | |
| 294 <code>hg rebase --continue</code>. You may run into multiple conflicts, | |
| 295 so just repeat until you're done. | |
| 296 </para> | |
| 297 | |
| 298 <para> | |
| 299 After rebasing you can start addressing the comments in your review and | |
| 300 commit them. Once they are committed, you can update your existing | |
| 301 review request with <code>rbt post --update</code>. If for some reason | |
| 302 <code>rbt</code> can not figure out the proper review request to | |
| 303 update, you can pass the number in via | |
| 304 <code>rbt post --review-request-id #</code>. Note that when using | |
| 305 <code>--review-request-id</code> you no longer need to specify | |
| 306 <code>--update</code>. | |
| 307 </para> | |
| 308 | |
| 309 <para> | |
| 310 Just like an initial <code>rbt post</code>, the updated version will be | |
| 311 in a draft state until you publish it. So again, you'll need to visit the | |
| 312 URL that was output, verify everything, and click the publish button. | |
| 313 </para> | |
| 314 </sect2> | |
| 315 | |
| 316 <sect2 id="land"> | |
| 317 <title>Landing a Review Request</title> | |
| 318 | |
| 319 <para> | |
| 320 This will typically only be done by the Pidgin developers with push | |
| 321 access. If you want to test a patch from a review request, please see the | |
| 322 <link linkend="patch">patch</link> section below. | |
| 323 </para> | |
| 324 | |
| 325 <para> | |
| 326 It is <emphasis>HIGHLY</emphasis> recommended that you use a separate | |
| 327 clone of the repository in question when you want to land review requests. | |
| 328 This makes it much easier to avoid accidentally pushing development work | |
| 329 to the canonical repository which makes everyone's life easier. Also, the | |
| 330 mainline repositories now auto publish, so if you do not selectively push | |
| 331 commits, all of your draft commits will be published. You can name this | |
| 332 additional clone whatever you like, but using something like | |
| 333 <code>pidgin-clean</code> is a fairly common practice. This makes it easy | |
| 334 for you to know that this clone is only meant for landing review requests, | |
| 335 and other admistrative work like updating the ChangeLog and COPYRIGHT | |
| 336 files. | |
| 337 </para> | |
| 338 | |
| 339 <para> | |
| 340 When you are ready to land a review request you need to make sure you are | |
| 341 on the proper branch. In most cases this will be the branch named | |
| 342 <emphasis>default</emphasis> and can be verified by running the command | |
| 343 <code>hg branch</code>. Next you need to make sure that your local copy | |
| 344 is up to date. You can do this by running <code>hg pull --update</code>. | |
| 345 </para> | |
| 346 | |
| 347 <para> | |
| 348 Please note, if you run <code>hg pull</code> and then immediately run | |
| 349 <code>hg pull --update</code> you will <emphasis>not</emphasis> update to | |
| 350 the most recent commit as this new invocation of <code>hg pull</code> has | |
| 351 not actually pulled in any new commits. To properly update, you'll need | |
| 352 to run <code>hg update</code> instead. | |
| 353 </para> | |
| 354 | |
| 355 <para> | |
| 356 Once your local copy is up to date you can land the review request with | |
| 357 <code>rbt land --no-push --review-request-id #</code> where <code>#</code> | |
| 358 is the number of the review request you are landing. The | |
| 359 <code>--no-push</code> argument is to disable pushing this commit | |
| 360 immediately. Most of our configuration already enables this flag for you, | |
| 361 but if you're in doubt, please use the <code>--no-push</code> argument. | |
| 362 </para> | |
| 363 | |
| 364 <para> | |
| 365 Once the review request has been landed, make sure to verify that the | |
| 366 revision history looks correct, run a test build as well as the unit | |
| 367 tests, and if everything looks good, you can continue with the | |
| 368 housekeeping before we finally push the new commits. | |
| 369 </para> | |
| 370 | |
| 371 <para> | |
| 372 The housekeeping we need to do entails a few things. If this is a big new | |
| 373 feature or bug fix, we should be documenting this in the ChangeLog file | |
| 374 for the repository. Please follow the existing convention of mentioning | |
| 375 the contributor as well as the issues addressed and the review request | |
| 376 number. Likewise, if this is someone's first contribution you will need | |
| 377 to add them to the COPYRIGHT file in the repository as well. If you had | |
| 378 to update either of these files, review your changes and commit them | |
| 379 directly. | |
| 380 </para> | |
| 381 | |
| 382 <para> | |
| 383 Now that any updates to ChangeLog and COPYRIGHT are completed, we can | |
| 384 actually start pushing the changes back to the canonical repository. | |
| 385 Currently not all of the canonical repositories are publishing | |
| 386 repositories so we'll need to manually mark the commits as public. This | |
| 387 is easily accomplished with <code>hg phase --public</code>. | |
| 388 <emphasis>Note</emphasis>, if you are not using a separate clone of the | |
| 389 canonical repository you will need to specify a revision to avoid | |
| 390 publishing every commit in your repository. If you run into issues or | |
| 391 have more questions about phases see the | |
| 392 <ulink url="https://www.mercurial-scm.org/wiki/Phases">official documentation</ulink>. | |
| 393 </para> | |
| 394 | |
| 395 <para> | |
| 396 Now that the changes have been made public, we can finally push to the | |
| 397 canonical repository with <code>hg push</code>. Once that is done, you'll | |
| 398 also need to go and mark the review request as | |
| 399 <emphasis>Submitted</emphasis> in the Review Board web interface. | |
| 400 </para> | |
| 401 </sect2> | |
| 402 | |
| 403 <sect2 id="patch"> | |
| 404 <title>Testing Patches Locally</title> | |
| 405 | |
| 406 <para> | |
| 407 If you want to test a patch locally for any reason, you first need to | |
| 408 make sure that you are on the target branch for the review request which | |
| 409 is listed on the review request page. In most cases this will be the | |
| 410 <emphasis>default</emphasis> branch. Regardless you'll need to run | |
| 411 <code>hg up branch-name</code> before applying the patch. | |
| 412 </para> | |
| 413 | |
| 414 <para> | |
| 415 Now that you are on the correct branch, you can apply the patch with | |
| 416 <code>rbt patch #</code> where <code>#</code> is the id of the review | |
| 417 request you want to test. This will apply the patch from the review | |
| 418 request to your working copy without committing it. | |
| 419 </para> | |
| 420 | |
| 421 <para> | |
| 422 Once you're done with your testing you can remove the changes with | |
| 423 <code>hg revert --no-backup --all</code>. This will return your | |
| 424 repository to exactly what it was before the patch was applied. The | |
| 425 <code>--no-backup</code> argument says to not save the changes that you | |
| 426 are reverting and the <code>--all</code> argument tells Mercurial to | |
| 427 revert all files. | |
| 428 </para> | |
| 429 </sect2> | |
| 430 | |
| 431 <sect2 id="cleanup"> | |
| 432 <title>Cleaning up a Landed or Discarded Review Request</title> | |
| 433 | |
| 434 <para> | |
| 435 Whether or not your pull request has been accepted, you probably want to | |
| 436 clean it up from your local repository. To do so, you need to update to | |
| 437 a branch other than the branch you built it on. In the following example, | |
| 438 we're going to remove the branch named | |
| 439 <emphasis>my-new-branch-name</emphasis> that we used to create a review | |
| 440 request. | |
| 441 </para> | |
| 442 | |
| 443 <programlisting> | |
| 444 hg up default | |
| 445 hg prune -r 'branch(my-new-branch-name)' | |
| 446 </programlisting> | |
| 447 | |
| 448 <para> | |
| 449 Now, all commits that were on the <emphasis>my-new-branch-name</emphasis> | |
| 450 branch will have their contents removed but interally Mercurial keeps | |
| 451 track that these revisions have been deleted. | |
| 452 </para> | |
| 453 | |
| 454 <para> | |
| 455 You can repeat this for any other branches you need to clean up, and | |
| 456 you're done! | |
| 457 </para> | |
| 458 </sect2> | |
| 459 </chapter> |
