ZenHub
Zenhub is an online issue tracker that allows us to track issues from all of our repos in one place. While the initial view can seem overwhelming ZenHub is simple to use and has sophisticated filtering capabilities that make it easy to focus on only the issues that are important to you. See the ZenHub Help Centre for more general guidance on using ZenHub.
- We track use cases and data sources as labelled epics in ZenHub. Any related issues should be linked to the relevant epic(s).
- We use a single board for all repo issues and rely on filters to provide focused views.
- New issues can be created in any repo directly from ZenHub using the most relevant template.
- It is useful to initiate conversations against relevant issues (as opposed to Matrix) for future reference.
- You are responsible for issues you are working on.
There are two main ways to interact with ZenHub. Both methods will require you to login using your GitHub account details. You will need to be a member of the CovidGraph GitHub organisation in order to create and manage issues. Please send your GitHub username to Jamie Munro (@jiros:matrix.org) to be added.
Login to The CovidGraph Board online
Install a browser extension that adds a ZenHub tab to Github. The ZenHub extension is available for Google Chrome and Mozilla Firefox. The ZenHub web app is also available for Safari and mobile. ZenHub supports the latest three versions for these official browser builds.
Zenhub calls its columns 'pipelines' and we have chosen to keep these as simple as possible. Currently there are five pipelines two of which are used to separate use cases and loaded data sources for easy reference.
Pipelines can be collapsed or expanded as needed.
- Backlog - Newly created issues from any repo land here automatically.
- In Progress - What the team is currently working on ordered by priority
- Closed - When an issue is resolved it will automatically move to the closed pipeline. Note, please keep use-cases and data source issues open. Completed data sources can be moved to the Loaded Data Sources pipeline.
- Loaded Data Sources - Data sources that have been successfully loaded into CovidGraph should be moved into this pipeline for easy reference. Please do not close issues
- Use Cases - A list of use cases logged as epics. Activity relating to any of the use cases should be tracked as separate issues linked to the correct epic.
It is easy to create new issues from ZenHub by clicking the green 'New Issue' button at the top left of the screen. Note that if you click the '+' you will get additional options and can create milestones and releases.
- Choose a Repo
When the new issue dialog opens you can select a repo in which to create your issue. The default is 'covidgraph/documentation'
- Choose a template
Some repos have issue templates for reporting different types of issues, for example use-cases, data sources and bugs. Templates also help to label issues consistently and to prompt for the correct information from the outset.
Note that it is still possible to create issues from GitHub itself but you will need to browse to the correct repo and its associated issue tracker.
When you create or open an issue in ZenHub there is a side panel with additional options to change the status/pipeline of an issue, to add labels, change assignments or link an issue to an epic. We are not currently using milestones, releases or estimates but may do so at some point in the future.
Issues can also be dragged between pipelines, for example to change status from 'Backlog' to 'In Progress'.
The ZenHub Help Centre has a good guide on filtering the board
CovidGraph uses several labels to help streamline issue tracking.
- The 'data-source' label identifies an epic as a data source. Related issues do not need to be labelled as data-sources but should be linked to a specifc data souce epic.
- The 'use-case' label identifies an epics as a use case and again, related issues should be linked to one of more use-cases as epics.
An example showing a filtered list of all data sources including suggested data sources that are either in the backlog or are in progress select the 'data-source'
For example, to see only the issues in the Visual Graph Explorer repo simply untick everything except 'visual-graph-explorer'
There are two ways to filter on epics. Firstly from the main filter or by using the 'Filter by epic issues' button that is built into all epic issue cards on the board by default. For example, here is a filtered view of issues relating to the data souce 'CORD-19'
