Below here is the content of the page from November 2022:

Integration Spec

MVP - Linked functionality only

Features

• Create Jira ticket from GH issue, on demand (by commenting)

• Create GH issue from Jira issue, on demand

• Designated links between issues in both systems

• Stretch goal: Display GH issue status on linked issue within Jira

Constraints

• Configuration: each GH project board has a corresponding Jira project

• Issues may appear on multiple project boards but we only support one Jira integration per issue so if an issue appears on multiple boards that have a Jira integration set up, that will just break.

Questions to Answer

(BTW: “and vice-versa” throughout)

• What Jira things should correspond to what GitHub things and vice-versa?

• On which side does the work flow start?

• How should the correspondence be established? (This can be in both directions, and answered differently for different directions, or different projects, etc.)

  • Implicit: for example: “all Jira tickets in project XYZ should create parallel GitHub issues in repo PDQ, and be added to project ABC.”

  • Explicit: Nothing happens until a comment is put on the Jira ticket with instructions, for example, “bot: create issue”.

  • Mixture: we have a table of Jira projects to GitHub repos/projects, but a comment is needed to start the process.

• What data is sync’ed between the two things? (This can be in either direction, and answered differently for different directions, or different projects, etc.)

  • Some Jira fields/tags/statuses/custom-fields/comments become GitHub issue/project fields/labels/statuses/comments?

• Do status changes on one side make status changes on the other side?

Use Cases

Linked: 1 GH Issue → many Jira tickets

• Support many Jiras to one GH issue

• Expose Jira issue status on GH, doesn't need attribute sync

Example: Jira tickets as action items from GitHub issues

Convenience utility for creating tickets in Jira to track work for reviewing OSPRs & provide advance notice for internal workstream interruptions. The status of a ticket may be tracked in GitHub until it requires the attention of the maintaining team (at which point a "review X PR" ticket can be created in Jira) or the maintaining team can use these tickets to plan ahead (e.g. make multiple review or technical discovery tickets and plan cycles for blended or FC projects).

Flows

• FED-BOM ticket on Credentials board

  • Issue exists on FED-BOM project board already (which has no Jira integration)

  • Credentials board engineer triages issue, moves to Backlog status, and comments to create a Jira ticket to review it.

  • A ticket is created in the corresponding Jira project

    • Jira ticket has a link to the GH issue (in the description?)

    • Jira ticket name is an arg provided in comment

  • The “private link” custom GitHub project field is populated with a link to that Jira ticket.

• OSPR against Credentials repo

• tCRIL FC ticket on Credentials board

Linked & Synced: 1 Jira ticket → 1 GH Issue

• 1:1 ticket relationship

• Useful to have attributes (description, etc) synced over time

Example: Parallel tracking for Epic tickets

Provide visibility for community into larger feature development work being done by the maintaining team. This is primarily for conveying status and providing a comprehensive technical roadmap for a given software component. Should link to wiki pages / approach docs for more substantive description and use standard conversation channels (e.g. Discourse & Slack) for discussion.

Example: Parallel tracking for Bugs & Technical tasks

Provide visibility for community around longer term technical roadmap tasks (e.g. support Tutor, upgrade Node) along with insight into how the maintaining team is prioritizing these tickets. Provides transparency around known issues that are not being worked on (e.g. no plans to support Tutor) and creates an entry point to solicit contributions (e.g. help-wanted flag).