Project transfer for Crucible

Installation

You can download it from the Atlassian Marketplace. It requires Crucible 4.8.0 or higher to run. You can use Administration > Manage add-ons to install it straight from your Crucible.

Usage

 Instructions below apply to the latest version of the plugin, older versions may have less features or more prerequisites.

Prerequisites

• target instance must not contain project of the same name and key
• target instance must contain all users involved in code reviews (author, moderator, reviewer) and project metadata (e.g. default reviewers)
• target instance must contain all groups involved in code reviews and project metadata (e.g. default reviewers)
• target instance must contain a permission scheme used by the project
• target instance must contain source repositories used in the project 
  • both defined as source roots in project's settings
  • and as source of commits in code reviews
• both source and target instance shall have the same, default set of defect classifications
  • if classifications have been edited, import plugin may not match them

Supported features

• code review metadata (author, moderator, reviewers, summary, objectives, dates, linked issues etc)
• files added in a review which originate from a repository (name of source repository, path, revision)
• comments (global and inline comments including replies, defects, linked Jira issues, author, date etc)
• uploaded files (attachments and patches) with comments 
• code branches

Unsupported features

• comment resolution status and read status - updating will work in Crucible 4.9.0 and higher
• code review history 
  • the audit log from code review page Tools > View Review History may show incomplete information or incorrect dates
• project metadata, including permission schemes and defect classifications
  • permission schemes and defect classifications are not created automatically during import
• users and groups
  • missing users and groups are not created automatically during import
• merging of projects is unsupported
  
  • you can't add code reviews from a source instance into a project of the same name on a target instance
• it's impossible to delete default CR project, so it's impossible to import it

Steps

• revoke permission to project being exported (set a permission scheme with no access) to ensure that no modifications will happen in the meantime
• export the project
  • go to Administration > Projects Settings > Export / import projects
  • select the project from the drop-down and click the 'Export' button 
  • wait until progress bar completes, once ready, the project will be shown in the Recently exported table
  • click the down-arrow icon to download the archive or trash to delete it from the server
  •  current version handles export / import of only one project at once, don't run it in parallel
• import the project on a target instance
  • go to Administration > Projects Settings > Export / import projects
  • choose file and click the 'Import' button 
  • wait until progress bar completes

Version history

Road map

In next iterations of the plugin we plan to add the following:

• comment resolutions and read status - Done for 4.9.0+
• defect classifications (all historical versions)
  
• content of files added from a source repository (it means that source repository will not have to exist on a target instance)

Troubleshooting

Enabling debug logging

Go to Administration > Server and click 'Turn debugging ON'.

Removing exported files manually

Exported files are stored in <java.io.tmpdir>/crucible-export-<project_key> folder.

Exported archive is stored in <java.io.tmpdir>/crucible-export-<random>.zip file.

Tracking code reviews, files and comments mappings

In case you have external systems, which store references to code reviews, review files or review comments, you can find ID mappings in the logs if debug logging have enabled during the import. Example messages:

Created review '<old id>' as '<new id>'


Created review item '<old id>' as '<new id>'


Created versioned comment '<old id>' as '<new id>' for review '<review id>'


Created general comment '<old id>' as '<new id>' for review '<review id>'


Created reply to comment '<old id>' as '<new id>' for parent comment '<new parent id>'

Some content of reviews is missing

Not all features are supported. If you enable debug logging you can learn more about content skipped. Example messages:

Skipping import of review item '<old id>' into review '<new review id>' as patches are unsupported.


Skipping import of review item '<old id>' into review '<new review id>' as attachments are unsupported.


Can't find review item '<id>' for a versioned comment '<id>'. Attachments are unsupported. Skipping comment and its replies.

Feedback

Please add comments to the https://jira.atlassian.com/browse/CRUC-681 suggestion.