What it really takes to migrate from one issue/project tracking system to another?

migrating-issue-project-tracking-system.md

Migrating from an issue/project tracking system to another

• An issue/project-tracking system is a living source of information for a team managing a project.
• It contains various history of discussions, decisions, links, comments, mentions, tags and labels...etc.
• When transitioning from one issue system to another, it is critical to maintain a high fidelity translation of the previous issues into the new system.
• Often, decisions to migrate are taken at a high level in your company for various reasons, but the execution of the migration could be not prepared and supported at all by your company. In that case:
  • Try to push this preparation to happen company wide.
  • Beware that your team might have to do it on its own because nobody is available to do this for you or, worse, to do it correctly.

What it really takes to migrate?

• Each migration is unique to a project even if most of the details can be generalized.
• Unless you have just very few issues in the previous system that you can migrate manually, you will have to develop a migration tool.
• The style/format of all the texts (description, comments) must be preserved as much as possible (headings, bold/italic, code region with the language, emoticons...)
• The internal links between issues must be mapped in the new system (old issue#1 to old issue#2 => new issue#1 to new issue#2)
• The author names of comments/issues descriptions must be preserved. A generic name with "cc" is not acceptable. Yes, it requires to have API tokens for each team folks in the target issue system.
• The dates of the issues/events must be preserved (authored, closed...)
  • Depending on your target system it could require that you need to input/translate issues/comments in the same chronological order than it was done in the original system (so it's not necessarily just foreach issues; copy issue; copy comments but instead replicate all actions in the same order)
• Maintain all mentions with target user names as well (might require a mapping and a verification tool for unknown names - sometimes target system doesn't have yet all target names)
• The milestone/labels must be preserved/mapped accordingly to the new system. Warning, that it could require a mapping from label to fields (e.g Label "High" maps to Priority "High" in destination system)
  • The destination system must be prepared with the target workflow. The migration could include a mapping of labels to match the target workflow.
• If the issue system was originally integrated with the Pull Request/repo system but they would be separated after the migration, it is highly important to maintain a similar dual-link integration where:
  • Mentions from an issue in the new system to a PR in the old system propagates a back-link.
  • Mentions from a PR to an issue propagates the back-link to the new system.
  • A PR mentioning in the description "Closes issue-XXX" should automatically close the issue on the new system.
  • All of this requires usually a bot/running server on the side. Check if your system provides such plugin but be prepared that you might have to develop one of your own.
• Nice to have: preserve/translate emoticons tags on issues if they apply.
• The migration tool can require to have a custom derived implementation/customization for each source project, depending on whether it matches the expected workflow/org of the target system.
• You need to run multiple test migrations on temporary destination projects to confirm that the migration will be smooth.
  • The results will have to be validated by the team before the final migration.
• You might have to migrate legacy interacting tools that were interfacing with the original issue system to post/fetch events.
  • Story can be complicated if the issue system has both a public user facing and private view.