diff options
author | Gary Kramlich <grim@reaperworld.com> | 2022-09-06 00:27:42 -0500 |
---|---|---|
committer | Gary Kramlich <grim@reaperworld.com> | 2022-09-06 00:27:42 -0500 |
commit | 19c19aa4003f96a9a056d54d4358e05e726fae9a (patch) | |
tree | 42773c012b4a5ca82ae4b8b1682dca82b13f70f6 /doc | |
parent | 64e93978ff82a18c4299bbe95473faa069949272 (diff) | |
download | pidgin-19c19aa4003f96a9a056d54d4358e05e726fae9a.tar.gz |
Replace the old contributing docs with a link to the online version.
Testing Done:
Built the docs and looked at them locally.
Reviewed at https://reviews.imfreedom.org/r/1728/
Diffstat (limited to 'doc')
-rw-r--r-- | doc/reference/libpurple/code_contributions.md | 330 | ||||
-rw-r--r-- | doc/reference/libpurple/contributing.md | 6 | ||||
-rw-r--r-- | doc/reference/libpurple/libpurple.toml.in | 3 | ||||
-rw-r--r-- | doc/reference/libpurple/mercurial.md | 85 | ||||
-rw-r--r-- | doc/reference/libpurple/meson.build | 3 |
5 files changed, 8 insertions, 419 deletions
diff --git a/doc/reference/libpurple/code_contributions.md b/doc/reference/libpurple/code_contributions.md deleted file mode 100644 index b571f1a4e9..0000000000 --- a/doc/reference/libpurple/code_contributions.md +++ /dev/null @@ -1,330 +0,0 @@ -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 administrative 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 or 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! - diff --git a/doc/reference/libpurple/contributing.md b/doc/reference/libpurple/contributing.md new file mode 100644 index 0000000000..cbe03370bd --- /dev/null +++ b/doc/reference/libpurple/contributing.md @@ -0,0 +1,6 @@ +Title: Contributing +Slug: contributing + +Contributing to libpurple is a bit different than other applications, but we +have documented everything you need to know in the official +[contributors guide](https://docs.imfreedom.org/contributors-guide/). diff --git a/doc/reference/libpurple/libpurple.toml.in b/doc/reference/libpurple/libpurple.toml.in index 0272c2279a..786238a2f2 100644 --- a/doc/reference/libpurple/libpurple.toml.in +++ b/doc/reference/libpurple/libpurple.toml.in @@ -37,8 +37,7 @@ base_url = "https://keep.imfreedom.org/pidgin/pidgin/file/default/" [extra] # The same order will be used when generating the index content_files = [ - "code_contributions.md", - "mercurial.md", + "contributing.md", "plugin_i18n.md", "plugin_ids.md", "signals_account.md", diff --git a/doc/reference/libpurple/mercurial.md b/doc/reference/libpurple/mercurial.md deleted file mode 100644 index 70a5835b3e..0000000000 --- a/doc/reference/libpurple/mercurial.md +++ /dev/null @@ -1,85 +0,0 @@ -Title: Using Pidgin Mercurial -Slug: using-pidgin-mercurial - -## Using Pidgin Mercurial - -### Introduction - -These instructions will help you clone a copy of any of the Pidgin -related [Mercurial](https://mercurial-scm.org) -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 -[Code Contributions](code_contributions.html) -page after you have successfully cloned the repository from this page. - -### Cloning - -In Distributed Version Control, ***cloning*** is the act -of acquiring a source repository. All of the Pidgin repositories are -hosted in Mercurial at -[keep.imfreedom.org](https://keep.imfreedom.org/). To -clone them you will be using the command -`hg clone <URL>`. The specific URL can be looked up in -the table below depending what you are trying to clone. - -> If you are trying to build Pidgin 3, you can just clone that repository and -> the build system will automatically clone the other repositories for you. - -#### Repositories - -[https://keep.imfreedom.org/gplugin/gplugin/](https://keep.imfreedom.org/gplugin/gplugin/) -: The plugin library used in Pidgin 3. - -[https://keep.imfreedom.org/libgnt/libgnt/](https://keep.imfreedom.org/libgnt/libgnt/) -: The toolkit library used in Finch. - -[https://keep.imfreedom.org/pidgin/pidgin/](https://keep.imfreedom.org/pidgin/pidgin/) -: The main Pidgin repository that contains LibPurple, Pidgin, and Finch. - -[https://keep.imfreedom.org/talkatu/talkatu/](https://keep.imfreedom.org/talkatu/talkatu/) -: The conversation widgets used in Pidgin 3. - -You can see an example clone of Talkatu below but all of the repositories will -output a similar result. - -```sh -$ hg clone https://keep.imfreedom.org/talkatu/talkatu -destination directory: talkatu -requesting all changes -adding changesets -adding manifests -adding file changes -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 -``` - -### Keeping Your Clone Up To Date - -If you are just tracking Pidgin development and are not contributing, chances -are you are still on the ***default*** branch. But let's make sure, and run -`hg update default`. This will change to the ***default*** branch if you're -not currently on it or do nothing. - -Now that you are on the ***default*** branch, you can -simply run `hg pull --update` to pull in all new changes and -update your local copy. Please note, if you accidentally run -`hg pull`, that is without the update, a subsequent -`hg pull --update` will not update to the latest revisions as -this invocation of `hg pull` did not find any new revisions. To -properly update in this scenario, you'll need to run -`hg update`. - -Below is an example of updating Talkatu when it's already up to date. - -```sh -$ hg pull --update -pulling from https://keep.imfreedom.org/talkatu/talkatu -searching for changes -no changes found -``` - -At this point you can review the code, build it, patch it, etc. diff --git a/doc/reference/libpurple/meson.build b/doc/reference/libpurple/meson.build index 0e4e909f29..2ec9bb737c 100644 --- a/doc/reference/libpurple/meson.build +++ b/doc/reference/libpurple/meson.build @@ -1,6 +1,5 @@ libpurple_doc_content_files = [ - 'code_contributions.md', - 'mercurial.md', + 'contributing.md', 'plugin_i18n.md', 'plugin_ids.md', 'signals_account.md', |