Skip to content

Latest commit

 

History

History
63 lines (46 loc) · 3.37 KB

readme.adoc

File metadata and controls

63 lines (46 loc) · 3.37 KB
Raw

Jira export

Please put an XML file here and reference it in org.ops4j.tools.jira2github.client.Client.main().

The file should be an XML export from Issues page of Jira project. I’ve prepared a JAXB model for XML having a root element like this:

<rss version="0.92">

Replacements:

&quotquot; -> &quot;
&quot; -> &quot;
&ququot; -> &quot;
&quoquot; -> &quot;
&gtgt; -> &gt;
&aapos; -> &apos;
&llt; -> &lt;
&lt;lt; -> &lt;
�� -> :wink:

What has to be migrated

  • Jira links are tough, as they require 2 passes for the migration

  • subtasks need a link in bottom-section of the issue

  • attachments are already handled, but point to Jira

  • Spring converts some Jira fields to GH labels:

    • issue type → type: *

    • status → status: *

    • resolution → status: *

    • component → in: *

  • markup - unquoted code blocks (like XML) should be quoted, to at least display XML markup - no need to wrap inside 3xbacktics.

  • @ mentions should be quoted

  • finally, it’d be great to add "last comments" to Jira issues, pointing back to Github

Tool usage

First we need an exported XML with all Jira issues - I get it using Jira UI, by going to e.g., https://ops4j1.jira.com/issues/?jql=project+%3D+PAXLOGGING+ORDER+BY+status+DESC%2C+priority+DESC&mode=hide and clicking Export → Export XML.

Before any issue may be imported to Github, target Github project needs some configuration.

Relevant versions.properties, types.properties, components.properties, resolutions.properties, links.properties and users.properties may be created using tests from org.ops4j.tools.jira2github.ParseTest

  • Github labels that represent Jira statuses, resolutions, issue types and components - this is done using org.ops4j.tools.jira2github.client.GithubLabelCreator

  • Github milestones that represent Jira versions.

    • org.ops4j.tools.jira2github.client.JiraVersionExporter copies the versions from Jira to Github

    • org.ops4j.tools.jira2github.client.GithubMilestoneExporter then prints a property-file formatted mapping of Jira versions to Github milestone numbers - this mapping has to be added to etc/versions.properties

org.ops4j.tools.jira2github.ParseTest.parseMarkdownAndOriginalMarkup() creates (in target/) a 2-column HTML file where we can compare the original Jira HTML with the Markdown translated to HTML using org.commonmark.renderer.html.HtmlRenderer.

Finally Jira issues may be copied to Github using org.ops4j.tools.jira2github.client.GithubIssueImporter - this is the most important part.

org.ops4j.tools.jira2github.client.GithubIssueExporter gets back the Github issues and prints property-file formatted mapping of Jira issue keys to Github issue ids, which has to be added to etc/issues.properties.

org.ops4j.tools.jira2github.client.JiraCommentCreator uses etc/issues.properties to add last comments to relevant Jira issues.

org.ops4j.tools.jira2github.ParseTest.printMarkdownForReferences() can be used to check if there are links related to projects which were not imported yet.

And really finally, org.ops4j.tools.jira2github.client.GithubIssueLinker is using the Jira-exported XML file again, together with etc/issues.properties, etc/links.properties and etc/projects.properties to update body of Github issues and set issue references.