NOTE: This is a very early draft of this document and is very incomplete.
The Apache Arrow project voted to migrate issue tracking from the ARROW project in ASF Jira to GitHub issues. This documents important information that is important for members of the Apache Arrow community to know about this migration.
TBD
TBD
Jira and GitHub issue content differ in serveral notable ways that impact migrated content. The following information documents the differences and decisions made negotiating them during the migration.
ASF GitHub Bot has commented on a number of Jira issues. Some of these comments cause failures when migrating to GitHub issues, and the project has elected to filter all GitHub Bot comments during the migration.
ASF Jira and GitHub track user identity independently, and there is no direct mapping of ASF Jira user account identifers to corresponding user accounts in GitHub. An attempt has been made to map ASF Jira and GitHub user identifiers based on past pull request activity, but this may be incomplete or contain errors. When an ASF Jira user account for which no corresponding GitHub user account can be found, ASF user information will be used.
User mentions in Jira issue content will be converted to GitHub user information using the same mapping table. If no mapping can be found, the ASF Jira username will be retained, escaped within a code block to prevent potential association with a different GitHub user account.
The GitHub issue import API provides no mechanism to specify the following during the import operation:
- Issue reporter
- Comment author
- Issue watcher
The issue assignee can and will be set during issue import, provided a mapped GitHub user account can be identified from the ASF Jira issue assignee user information.
Jira supports different issue "types", while GitHub issues do not have a top-level issue "type" field. A decision was made to map Jira issue types to labels to retain this metadata. The values are mapped as follows:
| Jira issue type(s) | GitHub label |
|---|---|
| Bug | Type: bug |
| Improvement, Wish, New Feature | Type: enhancement |
| Task, Sub-task | Type: task |
| Test | Type: test |
Jira allows tracking of components affected by an issue, while GitHub lacks a dedicated field for the same. This information
is mapped from ASF Jira values into GitHub issue labels with a Component: prefix. For example, a Jira issue with a
component value of Java will be mapped to a GitHub issue having a label of Component: Java.
Unlike GitHub issues, Jira supports a range of statuses. The GitHub import API only supports indicating whether the issue is open or closed; even variants of closed issues are not supported in the import API. As a result, no distinction can be made between migrated issues that were closed due as resolved versus those rejected as Won't Do. Furthermore, non-terminal statuses (e.g., Open, Assigned, In Review, etc.) all simply map to Open in GitHub.
Issue links appear in different ways:
- Sub-tasks formally tracked in a parent/child relationship
- Issues formally tracked as related using established Jira relationships
- Referenced inline in issue comments.
This issue establishs that the first two mechanisms will be captured and added to the issue description on the migrated GitHub issue. Inline comments linking to other ARROW issues will not be transformed to link to the corresponding migrated GitHub issue.
Issue attachment content will not be copied from ASF Jira to GitHub. Issues with attachments will have a list of attachments with links back to the content hosted on the source ASF Jira issue added to the description of the migrated GitHub issue. Any inline images in issue descriptions or comments will have the link converted to reference the ASF Jira source issue content to display correctly.
ASF Jira supports tracking the versions which an issue was discovered to initially affect (Affects version) and the version where the
issue is resolved (Fixed version). GitHub issues provides a single Milestone field. The Fixed version field in ASF Jira is
used to populate the Milestone field in migrated GitHub issues. The Affects version field values will not be retained in migrated
issue content.