Migrating from Ship 1.0

If you have existing data in Ship 1.0 that you want to bring over to Ship 2.0, and by extension GitHub, you can use the Migration Assistant built in to Ship 1.0.

Prerequisites

Before you migrate to Ship 2.0 / GitHub, you must first prepare the following items:

  • Ship 1.0 build 278 or later
  • GitHub Accounts for everyone who has an account with Ship
  • A GitHub organization in which all of the above accounts are members
  • GitHub Personal Access Tokens for each user with the repo permission.
  • GitHub repo(s) in which to place your migrated issues
  • Any GitHub labels that you want to apply to your migrated issues

Configuring Migration Step by Step

To launch the Migration Assistant, open Ship 1.0 (red icon), and choose Ship → Migrate to Ship 2.0 from the application menu.

Note

If you don’t see the menu item, use the Check for Updates… menu item to update to the latest build of Ship 1.0. If the menu item is there but grayed out, check your network connection or wait a moment for Ship to sync to the latest data from the server.

1. Map Ship users to GitHub users

For every Ship user that you wish to carry over to GitHub, you will need to ask them to create and provide you with a GitHub personal access token for the migration. They can delete their tokens once the migration has completed.

For any bot users that exist in your Ship organization or any users that don’t need their own user accounts on GitHub, you can just enter your own GitHub personal access token.

_images/users.png

2. Map Ship Components to GitHub repos and labels

While Ship 1.0 has a hierarchical component system, GitHub has a two level owner/repo hierarchy under which issues can be filed. Additionally, zero or more labels can be applied to each issue.

For each component in your Ship organization, choose a GitHub repo to migrate the issues into. You can choose the same repo for multiple components if you like, and use labels to organize your issues within the repo.

Warning

Each user configured in the first step will need to be allowed to create, edit, and comment on issues, as well as create milestones in any chosen repos for migration. A simple way to ensure this is to use a GitHub organization and make all of your users members of the organization.

_images/components.png

3. Map Ship Properties to GitHub labels

For each classification, priority, state, and keyword in your organization, you can assign zero or more labels to be applied to the migrated GitHub issues.

While keywords in Ship can have a value, labels in GitHub cannot, so for keywords it is simply the presence of the keyword on the problem in Ship that determines which labels will be applied to the corresponding GitHub issue. However, a table in the body of the GitHub issue will be created with each keyword/value pair, so no data will be omitted.

Note

Any specified labels must already exist in the destination GitHub repo. The migrator will not create labels that don’t already exist. You can use the web interface on github.com to ensure that the needed labels are in place for each repo to be migrated to.

_images/properties.png

4. Choose problems to migrate to GitHub issues

As a final step, you may choose which individual problems will be migrated to GitHub issues. By default, all problems will be migrated.

_images/problems.png

5. Perform migration

Once the migration begins, it is highly recommended to let it finish completely. Ensure you have adequate time, power, and network connectivity to finish the operation. Expect to migrate approximately 1 issue per second, where the limiting factor on migration is the GitHub API. While migration proceeds, a progress indicator and a log are displayed. You can also view the log at ~/Library/Logs/com.realartists.Ship.MigrationLog.

6. Additional Migration Details

Rich text comments are migrated to GitHub flavored markdown. This process is usually accurate, but some complex formatting may be lost.

Attachments are migrated to a host that supports serving files directly to users in a web browser without authentication. The URLs of the migrated attachments contain random 128-bit identifiers, however, making them highly unlikely to be guessed by anyone without access to your GitHub repos.

Timestamps on GitHub issues and comments will reflect the time of the migration, as opposed to the original time of filing in Ship 1.0, due to limitations of the GitHub API. The body of the issues/comments will include a footer indicating the original date of filing.

Relationships in Ship 1.0 are migrated to comment references in GitHub. GitHub doesn’t support relationships beyond related to, however the type of relationship will be indicated in the comment text. For example, a blocking relationship will be written as “Blocked by #XXX.”

GitHub numbers issues per repo starting at #1. If you migrate your issues to a single empty repo, your Ship problem numbers will be preserved in GitHub, but if you migrate to multiple repos or a repo that already contains issues, then the numbers will not line up. This is not generally a big deal as the migrated issues contain a note in them indicating which Ship problem number they were migrated from, and any relationships are correctly mapped in any case.

Migration does not modify your Ship problem database in any way.