Intro

The Workspace in ZenHub is where all of your issues will be managed. If you are using Scrum, then the issues are also the PBIs that are managed in your backlog. In order to help you understand what the Workspace is for, this document is broken up into the various uses of the Workspace.

Note: You will find several links in this document referring to the official ZenHub or GitHub documentation about their features. Be careful to read that documentation with a discerning eye. Their ideas for managing projects may well go beyond the scope of a small NPO like CDISC. Still, it can be helpful to understand their original intent.

Creating a workspace

A workspace can be created within the ZenHub tab that is available once you've installed the ZenHub extension for your browser. If a workspace already exists, you can select the workspace. Additionally, you can switch to a different workspace. The tool for select/switching a workspace exists in the toolbar on the left in the ZenHub tab, and at the top of the GitHub page in the bread-crumb trail wherein you can see the organization, repository, and workspace.

Status

The Workspace defines how you will apply a status to an issue (New, Closed, In Progress, etc). Any given status will be reflected in the Workspace Board as separate Pipelines (columns on the board). For instance there will be a New pipeline, a Closed Pipeline, and in the simplest case, an In Progress pipeline and not much more. If you use Scrum, there will be a Product Backlog Pipeline and a Sprint Backlog pipeline. When you first create a ZenHub workspace, you will get a default set of Pipelines.

Note: Issues on ZenHub can start as GitHub issues or as ZenHub-only issues. The difference between the two is important. GitHub issues can only be worked by someone having an account on GitHub. ZenHub-only issues start at ZenHub and cannot be seen within the GitHub issue list.

When would you use ZenHub issues? At CDISC we have not yet seen a need for ZenHub issues. However, a use-case for them would involve anyone providing a deliverable for your project that has no connection to GitHub. For instance, someone may be asked to produce a new logo, but that person doesn't use GitHub. Having that deliverable be in a ZenHub issue makes it possible for that person to work within in the project.

For the time being, all issues used in ZenHub start as GitHub issues which ZenHub will then manage. If you assign an existing repository to a workspace, that repository's issues will be assigned to specific Pipelines according to a default algorithm.

Common Pipelines

Below you'll find some of the most common pipelines (statuses) that have been used, and their definition.

• New: There is almost always a New pipeline. When an issue is first created within GitHub it appears in the New ZenHub pipeline. If an external individual (not on your team) creates an issue for a repository, this is where that issue will appear. Issues can be created in ZenHub in a pipeline other than New by clicking on the + icon at the top of the pipeline. A typical use case would be creating a New issue directly in the Product backlog pipeline. By default new issues show up in the New pipeline.
• Icebox: This is a pipeline where an issue is placed when it is still in an uncertain state. Typically the product owner has not decided whether or not to include it in the work of the team.
• Product Backlog: in scrum particularly, the product owner will store issues in the product backlog once he or she determines they have value for the product. The product owner will want to keep these in priority order (highest priority at the top) and make sure at least two or three sprints worth are ready to be worked on by the development team.
• Sprint backlog: in a scrum-based project the Sprint is the heartbeat of development. Work for the Sprint is planned at the beginning of every Sprint. PBIs that are selected from the top of the product backlog are put into the Sprint backlog by the development team.
• In Progress: as a developer begins working on an issue or PBI it is moved into the pipeline called In Progress.
• Review: when an issue or PBI needs to be reviewed by another team member it is typically moved into this column or pipeline.
• Done: once an issue or PBI is complete, or in the case of scrum has passed the definition of done, it is moved to the done pipeline and work ceases on that item.
• Closed: an issue or PBI can be moved into this pipeline by several means. If the issue is part of a release, often the workflow for the team says that it moves from Done to Closed. An issue or PBI can also move into this pipeline by being closed as unplanned or as a duplicate. In these cases the issue might have never been part of a product backlog or any other pipeline.

Less Common Pipelines

Some pipelines are included in the boards for some teams that don't always show up in other teams. Below you'll find a list of these and their definitions.

• Non-scrum team: this pipeline is being used by the core team to indicate issues that have been taken up by non-team members. Some volunteer might have presented a draft pull request or PR, and so the team takes the issue out of the product backlog and puts it in this pipeline. Or it may be that a contractor or some other CDISC person who is not part of the team is working on it.
• Ready for Review: it might be the case that you need this extra pipeline in order to help manage issues that have been completed but can't be reviewed right away. It may be because a non-scrum team member has submitted a request for review.

Whether your workflow is using scrum or some other mechanism you may well want to develop your own pipelines or statuses.

Workflow

The Workspace settings help you define the workflow that your team will use. You can define which pipelines refer to Product Backlog items, Sprint backlog items, in-progress items, review items, or completed items.

There is also the notion of a Workflow that goes between teams. Our organization is not so large and complicated that we need automated workflows from one team's workspace to another. If you come upon that topic when reading ZenHub's documentation, you can safely ignore it for now.

Repositories

In GitHub deliverables are part of a repository. Issues are also tied to a repository. For GitHub the repository is the most fundamental container for work. In ZenHub a workspace can integrate a single or multiple repositories. It is also possible for multiple workspaces to refer to the same repository. This use case is usually involving large organizations that need to have workflow across multiple teams. At CDISC this is probably not going to be an issue.

However it is distinctly possible, because we have small teams, that a single workspace might need to pull together multiple repositories. An example is the CORE team. They work on the engine repository, the rule editor repository, and others. When you have small teams it is often the case that the same people have to cover multiple areas. When using multiple repos, consult with the development team that will use the workspace so that it will only bring together repositories that have some organizational coherence.

Roadmaps

A roadmap is a way that an organization can plan the release or delivery of larger pieces of a product. In general you lay out over a timeline what you hope to achieve, week by week or month by month, on a larger scale. roadmaps typically do not concern themselves with a small day-to-day delivery items, such as PBIs. ZenHub does provide a connection between PBIs and larger themes. It does this by allowing you to lay out your planned delivery of epics in the roadmap. Since epics are usually composed of many smaller items, and ZenHub can reveal the completion of epics through their PBI count, it is then possible to get a sense of how the actual delivery of epics is proceeding.

The downside of using a roadmap with epics is that those who do not understand the process you are using might assume that the plan for an epic is a genuine expectation of the project. The expectation of any development project is that it will take as long as it takes. It always does.

The dissonance between a planned roadmap and the reality of development is handled, in a high functioning organization, by transparently adjusting the roadmap rather than enforcing faulty expectations. That is how, in a high functioning organization, a roadmap can be a useful tool in developing a vision and leading the organization with that vision.

The ZenHub documentation has a lot to say about roadmaps. Unfortunately much of it is for very large organizations that need to coordinate handoffs of deliverables from one place to another. We are not yet in that position at CDISC. So be careful to take with a grain of salt some of the things you read about roadmaps at ZenHub.

How to get started with roadmaps

The easiest way to get started with a roadmap is for a product owner to envision the large themes that need to be delivered for the product. Talk to your development team and allow everyone to Blue sky their ideas for how long these large themes will take. Enter those large themes as new epics for the roadmap and include those initial date guesses into the roadmap calendar.

With that in mind you can now see a planned implementation for the product. An oft-used paraphrase goes something like this, "No plan survives first contact with the enemy." Therefore be willing to update your roadmap often so that you can see the reality of development over time. The closer you get to finishing your product the more accurate your roadmap will become.