How it will work
Phase 1
Creating Jira issues from GitHub issues
Commenting on a GitHub issue can make a Jira issue.
Q: How do we find the Jira project to use?
An explicit mention in the comment. No: too laborintensive, error-prone, and repetitive.
The issue’s repo has an associated Jira project (somehow).
The issue is on a project board, and the project has an associated Jira project (somehow).
The GitHub issue will then get another comment with a link to the Jira issue.
Q: is there a better way? GitHub issues don’t have arbitrary links out.
The Jira issue will have a link to the GitHub issue.
I think we already have a field for this? “customfield_10904” (known as URL, but there are multiple fields called URL).
Creating GitHub issues from Jira issues
Q: Will it be enough for phase 1 to not do this?
Syncing information between Jira and GitHub
Q: As the GitHub status changes, what should change on the Jira side?
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).