Quick Overview of GitHub Issues

Exploration of Pros and Cons for OMRS

July 2020

Goal of this review

• Explore what can already be done with the free, existing Project features available on GitHub
• Try-out what it would look like to set up an OMRS project that connects to multiple repos, and see what pros/cons we could expect

Key Points of GitHub Issues compared to Jira*

Pros

• “GitHub is my second home already” - Sr Dev
• New dev users typically read GitHub documentation much, much more than Wikis
• One place - everything in GitHub!
• Very, very simple - easy to use, fast to learn
• Automated ticket workflows - e.g. merging a PR auto-closes the ticket
• Transparency - High visibility into our issues
• No Jira account hassle or learning curve
• Can bring together multiple repos under 1 shared Project or ZenHub Board
• Multiple projects can share 1 issue (could help w/ coordinating work with other squads, e.g. FHIR Squad)
• Labels perform most of the key functionality we tend to use in Jira, just in one simple place instead of multiple (e.g. priority vs complexity vs type etc)

Cons

• Very, very simple - mostly Kanban views, lose backlog view, not designed for intensive project management*
• Projects can only contain issues from repos under the same org*
• Built-in GitHub Project fx can only link to <= 25 repos*
• Milestones would be nice to track timelines (e.g. “Sprint 1”), but can’t use same milestone across multiple repos - so can’t use same milestone in a project with multiple repos *
• Issues must be linked to a specific repo (bit awkward for occasional general tickets, but probably a good practice overall)
• Visually feels like a lot!

* Note: This can be solved with an add-on like ZenHub; most of these add-ons require a paid subscription. ZenHub is free for public projects.

Labels simplify the many fields we see in Jira. Labels can be used to indicate everything from the issue Type, to priority, to other labels.

We can add issues to multiple projects.

Add as much detail in here with as much formatting or visuals as you want.

Milestones could be used for Sprint tracking, but have to be re-created for each repo.

Automated issue closing and movement through the project Kanban board with PRs.

Demo Issue

Link your PR to the issue here, and then...

Issue status auto-updates

Sprint status updated

Project Kanbans updated

Projects can be made private

Projects can be shared with specific teams

You can bulk-edit issues (e.g. change a Milestone or Label for multiple issues at once), but only within 1 repo at a time

OMRS Project Example

What would it look like compared to what we have now?

• Current Jira board vs Sample MF Squad Board/project in GitHub (just a few issues for demo purposes)

Other Public Examples

The next two slides show how the VS Code team and the MS Calculator feature team use GitHub issues.

• VS Code: They’ve used a column July 2019 to represent the work that’s next in-the-cue. We could use a similar approach for Sprints (e.g. Sprint 1) which would prevent having to re-label multiple issues every time the Sprint changes.
• IBM Carbon Design System: Heavily use labels to organize issues
• MS Calculator: Note how they have multiple steps before an issue is considered ready for work: first the issue is Pitched, then it goes through Planning, before technical Implementation is underway. This is similar to the simpler Backlog workflow step we’ve been using in Jira.

Real Example: GH Issues used by VS Code, in Project view

Real Example: GH Issues used for MS Calculator feature, in Project view

Real Example: GH Issues used for IBM Carbon, in Issues view (one massive list!)

What ZenHub webex gets us

​

(Using IBM’s Carbon issues as an example: https://github.com/carbon-design-system/carbon)

1. Get the free ZenHub webextension: https://www.zenhub.com/extension

2. See that a ZenHub tab appears in GitHub:

Managing Issues in ZenHub is mostly all about Boards

Labels are key - focus your board by filtering by labels (e.g. here we’re filtering by “bugs”)

Small amount of Reporting functionality

(Can at least see where issues seem to be backing up)