We walkthrough terminology, share views in Waffle and the corresponding view in ZenHub, as well as have tidbits around what additional functionality you'll get in ZenHub!
Last, we cover a few common questions we've received for teams migrating over. Don't hesitate to get in touch with any questions during your migration!
Get familiar with terms across Waffle and ZenHub
|In Waffle||In ZenHub||Notes|
Learn more about creating Workspaces
|Workspaces are made of a single, or multiple repositories. Learn more about multi-repo workspaces.|
|Repo (From GitHub)||Repo (From GitHub)|
Learn about all of ZenHub's Board functionality
|Sizes||Estimates / story points |
Learn more about estimating in ZenHub
|Throughput is measured in ZenHub in a similar manner to Waffle.|
As GitHub Issues move across ZenHub Boards, further to closed, ZenHub's Cumulative Flow shows how work items are flowing in and out of pipelines; while the Control chart measures average cycle and lead times.
Together, teams can track throughput, cycle time, and lead time.
|Milestone||Milestone||These are managed natively via GitHub, but ZenHub adds start dates to build Burndowns, and has a powerful multi-repo Milestone manager to help build robust Workspaces.|
|Epics||Epics||Instead of relying on keywords such as "parent of" or "child of" in the description field of issues and pull requests in Waffle, we give Epics a more prominent feature workflow, with an Epic creation button during normal Issue creation.|
This gives Epics epic-specific table views, progress reporting, and much more advanced functionality. Learn more
|Dependencies||Dependencies||In Waffle, dependencies are created using keywords such as "required by".|
In ZenHub, blocked and blocking relationship are created via a dependency section on the top of every Issue and Epic.
What's the same
- Waffle projects pull in GitHub Repositories.ZenHub Workspaces are built using repositories as well!
- Unique to ZenHub: In ZenHub, you can add multiple repos to a single Workspace. A Workspace is the equivalent of a Waffle project Board.
- Issue cards are GitHub Issues.
- These Issue cards pull the relevant metadata from GitHub Issues, including Milestones, Assignees, and Labels.
- ZenHub adds Milestone start dates to power our reports, such as the Burndown.
- PRs can be attached to Issue cards to track the status of code alongside an Issue.Learn about Issue <> PR linking
Mapping views from Waffle to ZenHub
Majority of the visual elements from your Waffle projects that you know and love are equally visible in ZenHub Workspaces! Here's some of the main ones:
- Labels carry over from GitHub Issues and are also present on each Issue card
- Using Issue <> PR Linking, ZenHub Issue cards show connected Pull Requests to help teams visualize what code changes are associated with an Issue.
- Assignees appear on the top of Issue cards, but on the left side. In ZenHub, if there's multiple assignees, multiple assignee profile badges will appear.
- The total story points and Issues in a pipeline will appear at the top of the pipeline.
- The repo where the Issue belongs appears on the top of every Issue card.
- In ZenHub, you can create multi-repo Workspaces. Bonus!
- In ZenHub, you can customize the name of a project/Workspace - While repos still belong to an organization, the Workspace name is your indicator for which project view you're in.
In ZenHub, there's enhanced navigation and other features that can enhance any migrated Waffle projects.
A few additional things we'd like to point out include:
- Each Workspace created has reports, including:
- Burndown (Tracking Sprints)
- Velocity (Tracking how much work is completed sprint-over-sprint)
- Release Reporting (Long-term project forecasting and scope management)
- Cumulative Flow (Tracking throughput, pipeline blockers, and work in progress)
- Control Chart (Tracking duration in certain pipeline stages, cycle and lead time, pace of delivery and throughput)
- You can create cross-Issue dependencies, establishing a blocked by or blocking relationship. These Dependencies appear on each Issue card for quick scanning and Issue management.
- Each pipeline can further be sorted by date, title, estimates assigned, and more! View the full list of Board functionality here.
- In our web app, you can also create multi-repo Milestones to manage Sprints in a Workspace much easier! Learn more
Various features in Waffle and matching features / UI in ZenHub
We've compared side-by-side the various Waffle functionality you'll be used to and what the corresponding via in ZenHub will be.
This is not a comprehensive list of all ZenHub functionality, but is intended to help you get familiar with the core features you're used to using in Waffle and what the new ZenHub experience will be.
|Accessing filters through the dropdown on a project||Accessing filters: on the top of every Board.|
|In Waffle, and/or selection appears before you filter.||And/or filtering appears in ZenHub once you toggle on more than 1 filter.|
|Excluding results in filters is done using a slider.||In ZenHub, you can use Board Settings to turn off PRs, toggle Issues, as well as hide elements on Issue cards to customize your view.|
You can also hide Epics through the Epic filter.
|Customizing pipelines in a project through Project Settings||Customize pipelines directly from each Workspace in ZenHub by double clicking a pipeline title, or using Pipeline Options via the cog on the top of any pipeline|
|Integrating with Slack in Waffle is through Project Settings||You can setup ZenHub's slack integration through Manage Organization from the sidebar, then navigating to Integrations Integrations in the Dashboard|
There is a dedicated Slack/Integrations setting in the Dashboard. This is also where you can generate custom API tokens for custom scripts.
|Adding Issues in Waffle is done through + Add Issue||In ZenHub, since you can work in a Workspace that supports multiple repos, we provide a few create options. On the sidebar, you can create Issues using Create, or, through the New Issues / + button in the Board. Using the + button gives you an option to create in any of your connected repos.|
|You can also choose to navigate to a different repo when in create mode if you selected the wrong one!|
|Similar to adding Issue metadata in any Waffle card, you can manage Issue metadata in ZenHub the same way.||We add additional layers making it easy to manage Issue hierarchy through Epics, or track long-term release projects by assigning an Issue to a Release from the sidebar.|
|Epics in Waffle are marked by bookmark icons on the bottom of an Issue card.||In ZenHub, we give Epics a more prominent position on the Board, with a Filter by Epic Issues filter on the card, Epic labels, and Epic badges inside the Issue.|
We do also suggest creating an Epic pipeline to better organize work on the Board. Learn more about best practices here
When Epics are created, you can also nest them for further hierarchy around large projects! Epic tables get created to track progress, report on complexity of a large Epic and much more. Here's a preview of a multi-nested Epic:
|Dependencies are marked by Required by # badges on the bottom of an Issue card.||In ZenHub, we show Dependency icons.|
These can be used to filter the Board to better understand the Dependency tree across all connected Dependencies.
In the Issue view, we add a section for Dependencies so individuals can also further view relationships, create new ones, and manage an Issue in one central location.
Waffle Bot automatically moved Issue to in progress when a branch was published. Does ZenHub do this?
At the moment, we support Issue to PR linking through a PR's UI in GitHub, which will connect the Issue and PR together as one unit on the Board; however, do not yet have automation related to branching.
Waffle Bot moved Issues when a PR was merged - how does this work in ZenHub?
When a PR is connected to an Issue and merged, we leave the Issue in the pipeline it was in at the time of merge. This is for a few reasons:
- Multiple PRs can be attached to an Issue
- We like to encourage ownership over an Issue, ensuring that individual teams get to choose what done means to them relative to Issues being closed. Not all teams match merged with released, so we don't want to assume just because the code was merged, the Issue should be closed.
Of course, don't hesitate to share your automation suggestions with us!
In Waffle, a GitHub label moved Issues across the Board to the corresponding pipeline and pipelines would auto-update the label to match. Why doesn't this exist in ZenHub?
At the moment ZenHub does not add labels to an Issue based on the pipeline it is in. We strive to provide a great UI experience in-app that encourages all team members to jump into the Board and take ownership over keeping projects updated and work organized. This encourages all team members to filter the Board for what's meaningful for them and take pride in owning team collaboration and communication.
As we've been developing ZenHub, we've heard from customers that they want to see less clutter on the Issue cards, so we've avoided adding such clutter that would create redundant information, like the pipeline being communicated both on the Board and via the label.
While we strive to make an experience everyone finds value in on the Board, we understand that some individual's needs aren't met by not having these labels. We do not have short-term plans to add this type of functionality, but this doesn't mean forever! Let us know what you'd like to see in our product portal.
We are going to miss Wafflebot :(
Everyone loves robots and waffles, we know!
Automation is high priority in our backlog, and we know without the robust automation of Issue cards you're used to, Board hygiene habits might take a bit to build up. While we can't share a timeline, we're working on table stakes features like roadmapping and project priorities, project hierarchy and team-specific views, and much more! Within all of this will be further product automation.
We also have a robust suite of free training and coaching to help you get familiar with a new setup and way of working. We'd love to chat with you!
Do you support GitHub's keywords for closing Issues?
We sure do! If you leverage the Closes/fixes keywords you know and love, we'll auto-close those Issues when the PR is merged that references the Issue. We can't however, move it to any other column apart from the Closed pipeline.
Can we create columns that are label dependant meaning that if issue has label "HIGH PRIORITY" set in an Issue, the card would automatically move to High Priority column?
Nope, but we have something even better than managing a separate pipeline! We're mid-development of support pinning Issues as high priority to the top of their respective pipelines.
This means you can manage highest priorities Issues along your entire workflow.
Check it out here and add your name to join early access in the coming weeks!