Consider using "GitHub link ( JIRA link )" cross-reference style

[vlsi]

If you consider GitHub issues to be primary, then it probably makes sense to put GitHub links first, and move JIRA links after GitHub ones for backup purposes only.

See https://github.com/mocobeta/forks-migration-test-2/issues/1872#issue-1328214873

Current formatting:

Linked issues:

• LUCENE-2025 (https://github.com/mocobeta/forks-migration-test-2/issues/2018)
• LUCENE-2026 (https://github.com/mocobeta/forks-migration-test-2/issues/2019)
• SOLR-139

Suggested alternative:

Linked issues:

• https://github.com/mocobeta/forks-migration-test-2/issues/2018 (LUCENE-2025)
• https://github.com/mocobeta/forks-migration-test-2/issues/2019 (LUCENE-2026)
• SOLR-139

[mocobeta]

Thanks for your suggestion. I considered the implications and effects of this change.

I'd prefer the current format - "Linked issues" or "Sub-tasks" are not GitHub features but Jira's features. We don't aim to recreate past Jira issues on GitHub, but we want to "migrate" Jira issues to GitHub while preserving the original contents as far as possible. cc @mikemccand

[vlsi]

Jira issues to GitHub while preserving the original contents as far as possible

In the new world, you would have GitHub issues only, and new issues would reference other issues and PRs. The habit would be: there's a link, you can click to see the details.

However, if you use "JIRA first, GitHub last" style for the migrated issues, then the pattern breaks.

Consider: "new issue 123 references a migrated one 42 which references yet another migrated one 21"

User opens "issue 123", and sees there's a link to 42, they click and open issue 42. So far so good. However, then they see "link to 21" which breaks the flow. They suddenly have to parse the message, and deliberately click on the second link (the first link for 21 would be JIRA).

That is why I suggest following the pattern: prefer in-GitHub links first, and keep JIRA links as the last resort, so cross-navigation between issues and PRs is consistent for both migrated and the new issues.

[mikemccand]

+1 to make the GItHub link prominent (first link) and then legacy Jira link after.

I agree we should design this for ease-of-use in a GitHub world.

[mocobeta]

OK, the change would be easy - I'll update the conversion script.

[mocobeta]

Addressed in #130.

[mocobeta]

Merged #130 - I'm closing this. Thanks @vlsi and @mikemccand for your suggestions.

[mocobeta]

I wonder if we no longer need links to Jira issue: #133. We already dropped the original Jira issue link for short form by replacing LUCENE-XXXX with #NN for succinctness.

[vlsi]

Looks reasonable to me. Then, the question is whether "migrated from jira" link is needed for every comment

[mocobeta]

I think we have to create the link to the original comment for fallback since we are noticing there may be minor conversion errors, although we tried to fix glitches as far as possible. Readers may want to quickly refer to the original comment in that case.

[mocobeta]

there may be minor conversion errors, although we tried to fix glitches as far as possible.

We noticed syntax conversion errors could be caused by various reasons such as wrong/complex usage of Jira syntax. I heavily tuned the Jira syntax parser library, but there still remain glitches like https://github.com/apache/lucene-jira-archive/issues/1#issuecomment-1200136651; correctly fixing them is difficult. In that case, we simply expect readers to refer to the original comment in Jira.

[vlsi]

Fair.

So GitHub link is just fine for "opening issues", however, comments are known to have weird formatting, so quick link to the source is indeed helpful