Crucible 101

First things first, if you haven't already got Crucible up and running carry out the following steps:

1. Download Crucible from the Atlassian Download Center.
2. Unzip the downloaded package to the desired installation directory.
3. Navigate to the bin sub-directory of your installation directory. Type/execute run.bat (under Windows) or ./run.sh (under Linux) to launch Crucible. A Crucible console window will appear, listing the startup progress. Give it a few minutes to complete.
4. On the same machine go to http://localhost:8060/ (or use the hostname or IP address in place of localhost from another machine). You will be prompted to enter a license key and set the admin password.

There are a lot of installation options. To learn more, see the complete documentation.

It should only take you a few minutes to have a running instance of Crucible. If you are still struggling after twenty minutes please contact our support team for assistance. They're ready to help at any time.

Once installed, you need to connect Crucible to a Source Code Management (SCM) repository, so that you can get reviewing right away. You can instantly connect to the following SCMs:

• Subversion
• Perforce

Using standalone Crucible, your repositories will be accessed only on-demand. However if using Crucible with FishEye you get much deeper SCM integration for Subversion, Git, Perforce, IBM ClearCase and CVS. FishEye allows advanced searching and rapid access to repository contents (it also requires pre-scanning your repositories). Note that your Crucible evaluation license enables FishEye.

See the configuration documentation for more.

Your Crucible instance must have at least one project, in a fresh install this is named "Default Project". It is a good idea to rename this to something more personal. If you plan on having multiple projects, you might also want to change the review key when renaming the Default Project (it defaults to 'CR'), this should not be the same as any other keys (e.g. JIRA project, Bamboo plan) that you use. At Atlassian we prefix our JIRA project keys with CR-, e.g. the FishEye project's key is CR-FE, but you can use whatever you like.

Crucible projects let you organise your reviews into logical groups, however they also serve several other purposes:

• Access control — is set at the project level
• Permission schemes — which roles can do what
• Default participants — e.g. auto add the team lead to every review
• Default length — set the number of week days to set the due date for a new review

You can also associate JIRA issue tracker(s) with your project by configuring JIRA Integration in Crucible.

Crucible can deliver email feeds based on user-configured parameters. For example, you can watch the contributions of a specific colleague or changes to a branch of code you're working on. To take advantage of this feature, you will need to tell Crucible about your SMTP server.

You can also configure custom templates for notification email messages and fine-tune the frequency of email delivery, for example, choosing a daily digest.

Move onto the next step to learn about Crucible's integration with JIRA, Atlassian's award-winning issue tracker.

1. If you already have a JIRA server set up, you can set up integration between your JIRA server and Crucible. Once established, activity on relevant JIRA issues will appear in the Crucible activity stream. JIRA issue keys will also be hyperlinked and a small information window will load when you mouse-over JIRA issue keys.
2. Visit the Crucible documentation for instructions on how to set up JIRA integration in Crucible.

Congratulations! Our support records indicate that over 80% of support calls happen during this installation phase. Once you have made it this far, the rest of the evaluation ought to flow smoothly.

There are heaps of tweaks and configuration options that you can experiment with. Check out the Crucible Administrator's Guide for more information.

Otherwise, move on to the next step and launch right into lightweight code reviews.

Using Crucible is easy and lightweight, facilitating rapid and effective reviews. Jump right in and create your first review now .

There are many carry out reviews with Crucible. In some form or another you need to go through the following steps. Each step is linked to documentation, but you probably won't need it.

• Create the review - Select "Create Review" from the "Tools" menu in the top right of any page. 
• Add content to the review - Choose some stuff to review, either from a repository you have configured or by uploading something.
• Choose reviewers - if you haven't added users or [configured ldap] you won't be able to do this, you'll get a warning when you try to start the review, but you can ignore that
• Start the review - click the start button in the create dialog or in the top right hand corner of the review page
• Add some comments - use one of the many "add a comment" links or simply click on the lines of source your want to comment on
• Summarise and close the review - when you are finished with a review, it needs to be closed. Summarise is the state between "under review" and "closed", most of the time you will summarise and close at the same time. Alternatively you can abandon a review, which effectively moves it to the trash.

Now that you've got a feeling for the basic review concepts, its worthwhile taking a moment to customise your instance.

Pre commit
Crucible allows you to review a change before it has been committed. To do this, you upload a patch file to the 'Patch' tab (or paste it in as text) when creating a review. You must first generate this patch file from your repository, using either commands built into your IDE, or via the repository command-line tools.

• Create a new review. From the 'Tools' menu in Crucible, select 'Create Review'.
• Click 'Pre-Commit - Upload a patch file to be reviewed'. The 'patch upload' dialog appears. Click 'Browse', locate your file, then click 'Upload'. Crucible will now search for matches in the files in its database. Crucible will analyse all the paths in the patch, find the branches containing all those paths, then anchor the patch to the trunk or the branch with the most recent commit activity.

Learn more about pre-commit (patch) reviews here.

Post commit

• Create a new review. From the 'Tools' menu in Crucible, select 'Create Review'.
• To add files to a review, click the 'Files' option on the left navigation bar of the Manage Files dialog. The Files view opens.

Learn more about post commit reviews here.

• When adding reviewers, Crucible will suggest reviewers who have worked on the relevant files, but also don't have a big review backlog.
• You can set a specific due date for each review as you create them, or set a default duration for each review under a project.
• You can easily link to JIRA issues in reviews and associate reviews with JIRA issues.

• You can easily highlight defects in the code under review by click on the 'Defect' checkbox when commenting.
• All 'Defects' can be classified with a priority
• Crucible tracks the time you have spent on each file in a review and also your progress through the review.

Try hovering your mouse over the following links in Crucible to see the context windows:

• Crucible usernames,
• JIRA Issue Keys (when using JIRA; see the documentation).
• CSIDs (when using FishEye; see the documentation).

This information appears as a stream on the Dashboard and oher index pages, sorted chronologically showing you the latest changes. Updates can be viewed as an inline stream or RSS feed. See the documentation for more.

On the People index page, you can see the commit history in global lines of code (LOC) that each person has contributed (expressed as a line graph) and their total number of commits. Also, the most recent piece of activity is shown as a clickable item. See the documentation for more.

You can click on a person's name to see detailed information about their code reviews, showing details of their work and summaries of their activity. Additionally, you can see their work on tracked issues and additions to the repository if using Crucible with FishEye and JIRA integration is set up. See the documentation for more.

Click the 'Dashboard' tab to see a stream of all your own activity; your reviews; your personal code commits (if you are using FishEye); and your tracked issue updates (if you are using JIRA). See the documentation for more.

In Crucible, you can add the following items as favourites:

• Reviews,
• Review Comment Threads,
• Projects,
• People,
• Changesets,
• Files or Folders,
• Repositories.

Once items are added to your favourites, a list is created. You can then view it or see a stream of all activity relating to your favourites.

See the documentation for more.

• Configure your Email preferences.
• Check out the handy Blocker report and JIRA Blocker Reports. Every now and then, someone in the team can become a bottleneck in the review process. The review blocker reports help by identifying team members that have a lot of reviews waiting in their inbox.
• Configure your personal dashboard and set up RSS feeds.

Searching for Reviews:

• Using the Filters Navigation Bar
  • 'Everyone's Reviews' Filters
  • Custom Filters
  • Review State Filter
  • Comment Search

See the documentation for more.

Searching for comments:
Crucible give you the ability to search and filter review comments. Search or filter by comment content, defect classification, specific role(s), date and much more. Learn more here.

You can quickly find what you are looking for by typing one word or part of the name of what you are looking for. Crucible's Quick Nav feature will immediately show matches and suggestions below, before you've even pressed Enter or activated a proper search. Try typing a review's issue ID to go directly to that page.

• When files in a review become outdated, Crucible informs you with the File Outdated Menu. You can then easily update the file with one click (Iterative Review).

• When adding files to a review, you can also review multiple revisions of a file.

You can create your own report as a plugin and have it appear in the menu. For example, the 'Review Blockers' report that appears in the user interface is actually a plugin, added in to Crucible. You can use this plugin as a basis to create your own custom reports and add them in to Crucible. See the Crucible developer documentation for more.

With its own API (Application Programming Interface), Crucible is extensible. If you need Crucible to do more than it ships with and you've got programming chops of your own, the API allows you to build extensions to the application to suit your needs.

See the API documentation for more.

There are several aspects to the JIRA and Crucible integration. Each link below will take you into the details of each.

Create Reviews from inside of JIRA:
Learn how to create reviews from JIRA here

Associate and create JIRA issues for your reviews:

• 1. Create a JIRA Issue for your Review
• 2. Create Your Review and Link it to a JIRA Issue
• 3. Make a Comment or Defect on the Review
• 4. Click to create a JIRA Sub-Task
• 5. Resolve the JIRA issue through Crucible

Using the free Atlassian IDE connector you can create, work with, manage, and monitor all your Crucible reviews directly from Eclipse and Intellj.

Some highlights include (this is a sample from the Eclipse Connector):

Below are the highlights of viewing and acting upon Crucible reviews within Eclipse.

• Receive notification of new and updated reviews.
• View the review details in an Eclipse editor.
• Open the file under review, at the commented source code line.
• Create a post-commit review, a patch review or a pre-commit review.
• Summarise and close the review and perform other workflow actions.

• Wiki markup in your review comments - this is a way to make your comments stand out.
• Keyboard shortcuts - Keyboard shortcuts can help save some time on creating, editing, and working with reviews.

• In Crucible, you can set configure defaults per-project for review duration, review objectives and reviewers.
• Crucible allows you to customise your own permission schemes.
• Crucible lets you disable the moderator role, for lightweight, faster peer-to-peer reviews.