Initiating a Crucible review from code in your local repo

[rarified]

Crucible, the code review tool we have available at the Foundry, is only able to display code that is present in one of the OpenUru repositories (either from the Foundry or BitBucket). This is because an administrator must configure Fisheye to add additional repositories (such as forks from one of the OU repositories), and that would be impractical for a large number of users or forked repositories.

This note is a preliminary draft of a Wiki article describing how to use Crucible to conduct a review of code that is not currently present in OpenUru repositories. It is as much a place for me to note the process down as a reminder for myself, as is will be a presentation to others of the procedures. Note: I'll be editing this page to fill out TBD sections over the next day or so, this is just to get started.

Overview The process involves constructing a "patch" file from your forked repository which describes the differences in each file between your repository and the OpenUru repository. You need to use the Mercurial tools to do construct this file. With the patch file in hand, you can initiate a review of the appropriate OpenUru project in Crucible, by importing the patch file into the review. This will construct a working copy of the file, as it appears in your repository, for reviewers to work from. The review can then proceed as though your changes were already available as part of the appropriate OpenUru repository.

Step 1: Ensure your fork is synchronized. The first step is to make sure your local fork and repository is up-to-date with any other changes that may have been added to the OpenUru repository since you forked or last updated your repository. This is to ensure there is a common ancestor revision in both the OpenUru repository and your own repository (which is the starting point for producing a patch).

If you did not use BitBucket, skip this paragraph. First, you need to make sure your BitBucket fork is synchronized with the original repository you created a fork from. Navigate to your fork repository home page. There should be a Compare Fork button in the repository description box at the top of the page. Click Compare Fork... if there are changes in the original repository, you will be prompted to perform a "merge" of your BitBucket repository and the parent repository (merging is beyond the scope of this document).

Now you need to synchronize your local repository (on your local computer) with the parent repository (either the Foundry repository or your own BitBucket fork). How you do this depends on which Mercurial tools you are using.

Step 1.1: Updating with the Mercurial CLI. You will use the hg pull command to update your repository, like this:

Code: Select all

shell$ hg pull -u

The -u option asks Mercurial to update your working files after synchronizing the local repository with the parent repository. If conflicts exist in files, Mercurial will attempt to merge the differences between the parent and local repositories automatically. For simple differences, or files that are changed in one repository but not the other, this usually succeeds without intervention. But in more complicated cases, you may have to perform the merge yourself. Research Mercurial merging for more information.

Step 1.2: Updating with TortoiseHG toolkit. Use the Synchronize button at the top of the main toolbar to bring up the synchronzation tool panels. In the tool panel, there should be a Post Pull button which when clicked offers a Post Pull Behavior popup window. Be sure the Update option is selected, and also usually you will select Automatically resolve merge conflicts where possible. Save that configuration, then on the toolbar, select the Pull incoming changesets... operation. TortoiseHG will pull any pending changes from the parent of your local repository, and then update your working files with those changes. Again a merge may be necessary.

Step 2: Obtain a patch file corresponding to your changes.
TBD

Step 3: Create a Crucible Review.
TBD

Step 4: Import the patch(es) to the Crucible Review.
TBD

Step 5: Begin the review process.
TBD