This documentation relates to Crucible 2.2.x
If you are using an earlier version, please view the previous versions of the Crucible documentation and select the relevant version.

Skip to end of metadata
Go to start of metadata

Welcome to Crucible 101, an introductory guide to Crucible and a tour of the most interesting Crucible features. Use this page to guide your evaluation process or quickly get up to speed with Crucible.

Crucible 101

Thanks for taking the time to try Crucible. To help you make the most of your time, try these easy instructions for configuring and using Crucible. 

Software developers are the intended audience for this document.

Getting Crucible up and running

Carry out these steps to setup Crucible and you will be ready for your first code review in no time. Setting up Crucible takes less than half an hour.

Install

  Basic installation is a breeze. (click to expand)

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. Launch Crucible from the command line, typing run.bat (under Windows) or ./run.sh (under Linux). A Crucible console window will appear, listing the startup progress. Give it a few minutes to complete its process.
  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.

Connect to Your Repository

  Crucible standalone supports SCM repository systems. (click to expand)

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:

(info) Using standalone Crucible, your repositories will be accessed only on-demand. However if using Crucible with FishEye you get much deeper SCM integration for SubversionGit, 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.

Set Up Your Crucible Project(s)

  Work streams in Crucible are organised into projects. (click to expand)

Your Crucible instance must have at least one project, in a fresh install this is imaginatively 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. 

Obviously Crucible projects let you organise your reviews into logical groups, but they 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.

Configure Mail (optional)

  Email notifications are a great way to keep up with Crucible activity. (click to expand)

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.

Configure JIRA (optional)

  Crucible integrates with JIRA, Atlassian's enterprise issue tracker. (click to expand)
  1. If you already have a JIRA server set up, you can go ahead and set up integration between the two. Once established, activity on relevant JIRA issues will appear in the Crucible activity stream. JIRA issue keys will also be hyperlinked, also 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.

Setup Complete!

  Your Crucible instance is now established. (click to expand)

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.


Learning the Basics

Now that you've got Crucible set up, you can start using Crucible's code review features in earnest. Creating reviews, pre-commit and post-commit reviews, notifications, and much more.

Creating Reviews

Reviewing Quick Start

  Jump into code reviews instantly with Crucible. (click to expand)
Icon

If you are getting familiar with Crucibles structure - roles, workflow and parts of a code review please refer to the following document before moving forward.

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 and Post Commit Reviews

  Create reviews before or after you check-in. (Click to expand)

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.

Creating Reviews Fields

  Fill in the fields that are relevant for your review. (click to expand)
  • 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.


Working with Reviews

Comments turned into defects

  Identify defects in your code and tag them in Crucible. (click to expand)
  • 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.

Context Windows

  A number of context windows appear when hovering your mouse over links. (click to expand)

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


Activity & People

Crucible adds a modern social web dimension to the usually impersonal data stored in your Source Code Management (SCM) repository.

Activity Streams

  You can see commits and updates from the users in Crucible rolling by. (click to expand)

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.

People Lists

 In Crucible, you can view useful updates and statistics from your team. (click to expand)

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.

People Pages

  Each person who makes code changes has a page. (click to expand)

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.

Your Personal Dashboard

  See your own work at a glance and a stream of work items that are relevant to you. (click to expand)

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.

Favourites as Bookmarks

  Everything in Crucible can be bookmarked. (click to expand)

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.

Subscribe to Crucible Updates

  Keep track of Crucible activity when your Crucible session is closed. (click to expand)


Search Options

  Find a specific review or all of them with easy search options. (click to expand)

Searching for Reviews:

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.

Quick Nav

  When you type in the search box, matches are instantly shown below. (click to expand)

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.


Advanced Features

Crucible will allow you to go beyond commenting on source code. Iterative reviews, reports and auditing, plugins, JIRA integration, IDE integration, and much more.

Iterative Reviews

Files are always up to date

  Crucible allows you to review iteratively, so you can keep focused on the most recent file. (click to expand)
  • 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).

Review Multiple Revisions

  Select the files that you want to review


Reporting

Plugin Reports

  Crucible is extensible, allowing you to create your own reports and sent info to other systems. (click to expand)

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.

Using the REST API

  Extend Crucible. (click to expand)

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.


Integrate with other systems

Integrate with JIRA issue Tracker

  Link your code reviews directly to your JIRA issues

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:

Integrate with your IDE

  Create and work with reviews in Eclipse, Intellij, and Visual Studio

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

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

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


Tips and Suggestions

  Get reviewing quicker with these suggestions


Configuration Tips

  Unleash the flexibility of Crucible by configuring it exactly to your needs. (click to expand)


Thanks for taking the time to evaluate Crucible using this guide. To help continue your journey, our support staff are always ready to answer your questions in the Crucible Forum, or solve specific problems at our support portal http://support.atlassian.com.

  • No labels