Phase 2: Transfer issues from Jira project to GitHub repository

Technically it's possible to transfer issues from Jira to Github as soon as issues are enabled for the repository. However, there need to be some preparations.

A config is needed and is prepared by Sandra Parsick. She also does a test for each repository to a test repository. A Maven committer needs to do the "real" migration, because of the rights needed.

Planed project order

First some smaller projects will be migrated to ensure that the tool works.

After that wishes are that Maven core and the core plugins should be migrated with a higher priority in preparation of Maven 4.

Guillaume Nodet:

ok, i would think, now that the process has been experimented, the most important is the main MNG one, then the core plugins.  Those that users faces the most.

Precondition

There need to be a config class for the JIRA project/component to be migrated.
Those are programmed by Sandra Parsick. She also does a test run for those.

Only projects with a such a config can be migrated. If configuration is missing for the project to be migrated, reach out for Sandra (for example on Slack).

Step 1: Get access-token for service account 

The actual migration execution is done, using a time limited service account named "jira-importer" provided by INFRA.
For this an access-token is needed. Ask PMC Benjamin Marwell to get the token.

Step 2: Clone migration tool

Clone the migration tool from "https://github.com/support-and-care/jira-to-gh-issues"

Step 3: Prepare run configuration in application.property

In the application.property (location: src/main/ressources) the following things need to be set and/or matching the project to be migrated

• github.access-token (line ~12): The token for the service account (Make sure to NOT commit/push this information!)
• jira.base-url (~17): The URL of the JIRA server, should always be https://issues.apache.org/Jira
• jira.projectId (~24): The name of the JIRA project, e.g MRAR
• github.repository-slug (~39): The name, including organization, of the target github repository, e.g. apache/maven-rar-plugin

Warning: Make sure that "github.delete-create-repository-slug" (~45) is ALWAYS set to FALSE. Otherwise the script will try to delete and recreate the target repository (which will fail)

Step 3.1: Optional configuration

• If JIRA issues for a component of a shared project are to be migrated the name of the jira component name must be set for the "jira.component" property (~28).
• If the JIRA project has too many issues (more than 700?), they have to be migrated in multiple runs. Each run has to define a JQL query to only select a subset of all issues. This JQL is set in the property "jira.migrate-jql" (~60). In general Sandra will prepare those JQL during her test runs.

Step 4: Build migration tool

Build the migration tool with the given configuration using "mvn clean package -DskipTests".

Notes:

• Tests are not working as they are designed for the original purpose of Spring (Info: Skipping surefire is set in the plugin's configuration of the pom.xml now)
• The build needs exactly Java 17 and Maven 3.x (Enforced via enforcer-plugin now)

Step 5: Disable notification by contacting INFRA

During migration a lot of issues and comments are created. To avoid spamming at least the notification ML, those should be disabled for the time of the migration.
To do this comment out the lines "issues: issues@maven.apache.org" and "pullrequests: issues@maven.apache.org" (or whole notifaction block) in the asf.yml (on master branch) configuration of the target repository.

Disabling notifications in asf.yml does not work. Infra needs to be informed at least 30mins before migration which GitHub repository needs to get ignored sending events. 

Step 6: Prepare run

Copy the created jar from step 4 into a folder and make sure that no "github-migration-failures.txt" is there before run
This file gets created during execution if errors occurs.

If you start migration on project without any former migration run there must also be no "github-issue-mappings.properties" (contains mapping of Jira issue key to Github issue number) and "github-issue-pendings.properties" (contains the last migrated JIRA issues and acts as a reentry point when continuing a migration run) file. 

These files ARE needed when continuing a runAlso make sure that your local webservice port 8080 is not used. The tool needs this port during execution.

Step 7: Execute tool

Execute the tool via command line, using "java -jar jira-to-gh-issues-0.0.1-SNAPSHOT.jar" (adjust path to artefact if not executed within same folder)

Step 7.1: Check log

Check log for errors. If there are such, fix them and rebuild the tool and/or rerun the build.

Experiences errors

Step 7.2: Add Jira comments with links to created GH issue (optional but recommended )

To let users know that an Jira issue has been migrated to GH issues, the class/app "LastJiraCommentApp.java" exists in "src/main/java/io/pivotal/post".

This creates an comment in the Jira issues with an information and a link to the created issue.

The app requires

• "jira.user" and "jira.password" properties (with your personal values) in "application.property"
• the "github-issue-mappings.properties" (created during migration) in to the root folder of the Maven project (not in target or where ever you ran the jar file)

Step 8: Enable notification again

If migration is completed, don't forget to enable notifications in asf.yml again.

Step 9: Remove old issue Jira link from config

Remove the link to old Jira issues from the ".github/ISSUE_TEMPLATE/config.yml" (Example PR: https://github.com/apache/maven-apache-parent/pull/524/files)

Step 10: Check milestone list

We need exactly one open milestone in order to detect which is current.

If we need more than one open milestone, we have to add a branch to the milestone description

branch: <branch name>

This identifies the default for that branch.

https://github.com/apache/maven-gh-actions-shared?tab=readme-ov-file#milestone-configuration