Agile Project Management with GitHub + Zenhub
The Data and Technology Services team is using GitHub and Zenhub for agile project management. This is an overview of our process.
Set up
Create a GitHub account if you don't have one already.
Have someone on the DTS team add you to the City of Austin organization and the Transportation team as a Maintainer.
Add the Zenhub extension to your browser.
Log into the Zenhub web app using your normal GitHub credentials to activate your account.
Pipelines
The Zenhub board uses a Kanban-like format where issues are represented as cards and move across the board as they enter various stages of completion. Our workspace pipelines are:
New Issues - Awaiting triage by Level I Support or Product.
Icebox - Recorded and understood, but not committed to. Lack of evidence of overall value or applicability. We don't want to delete these and create a cycle of raising duplicate issues, so we keep them in our icebox with just enough information attached that we can pick it up sometime in the future — if and when we choose to do so.
Needs Scoping - Potential projects or features that require clarification or exploration before presenting to builders for estimation and prioritizing.
Backlog - Issues that are ready to be tackled by the team when the time comes. This pipeline is prioritized: the higher an issue is on this list, the higher the priority.
On Deck - Slated for work in the current sprint. During Sprint Planning, we pull all issues that we intend to work on during the sprint into On Deck.
Blocked - Issues that cannot be completed — often waiting on CTM or user feedback.
In Progress - This one is self-explanatory. Each Issue in this pipeline should have an assigned owner who is responsible for its completion.
Ongoing - Continually supported products and activities.
Review/QA - Proposed as complete but awaiting approval — code review and/or acceptance testing — before closure.
Ready to Deploy - Code or configuration that is ready to be deployed to production.
Closed - Done! 🙌
Issues
Tracking our work in issues not only helps us stay organized, it gives us data on where we're spending our time. To create an issue, click the green "New issue" button in the upper right corner of the "Issues" page or our Zenhub board.
You will see a list of our custom issue templates. These are handy for creating bug reports, meetings, etc. with boilerplate information and structure.
Issue Titles
It is best practice for issue titles to begin with a verb and summarize the work to be completed. This convention improves readability and helps keep our tasks action-oriented and unambiguous.
Here are some examples:
| Use this | Not this |
|---|---|
Replace the council district dataset used in Vision Zero Viewer | Outdated/inaccurate council district AGOL resource in VZV |
Implement new work activity fields in the Moped editor UI | AMD not tracking funding information |
Publish new CCTV camera thumbnails | CCTV map issues |
Labels
You can apply labels when looking at an individual issue by clicking the "Labels" heading in the right-hand sidebar. You can also apply labels in bulk from on our Zenhub board.
Labels allow us to view related issues across the Zenhub pipelines. For example, during Apps Team Sprint Planning, we filter down to Service: Apps and during our periodic meetings with AMD we use the Workgroup: AMD label to look at all the work — across teams, of all sizes — that we're doing for them.
All to say: It's important to ensure issues are properly labeled.
Required labels
Workgroup — the customer we're serving;
Workgroup: DTSfor internal work andWorkgroup: ATDfor department-wide workService — The DTS service team the work will be handled by
Project and/or Product labels
Projects refer to a substantial scope of related work that will reach a state of relative completion, such as the AGOL Audit
Products are solutions that we continue to support over time, including all in-house applications, such as the Vision Zero Crash Data System
Often, a major feature or enhancement to an existing product will require enough resources and coordination that it qualifies as a project. Warehouse Inventory, for example, was a major set of features and enhancements to AMD Data Tracker and the Finance and Inventory App, so it needed both Product and Project labels
Optional labels
A DTS team or individual product manager may find these additional label categories helpful
Type — The type of request or task
Impact — The effect of a bug, infrastructure failure, etc.
Impact: 1-Severe— Severely impacts TPW service deliveryImpact: 2-Major— Causes a major interruption of TPW service deliveryImpact: 3-Minor— Deteriorates TPW service deliveryImpact: 4-None— Does not affect TPW service delivery
Need — To designate priority of a potential feature or enhancement
Impact: 1-Severe— Severely impacts TPW service deliveryImpact: 2-Major— Causes a major interruption of TPW service deliveryImpact: 3-Minor— Deteriorates TPW service deliveryImpact: 4-None— Does not affect TPW service delivery
Provider — The external team or vendor executing the issue
Estimates
Estimates are how we track the level of effort of issues. This is useful for
Sprint planning to see when a person or team has too many issues (or too few!) issues assigned to them
Stakeholder discussions when prioritizing features — being able to show stakeholders easily that we can accomplish, say, three small tasks, two medium, or one large
Velocity tracking, which helps us predict the likelihood we can complete things by a given date
This is a good article about the hows and whys of estimates with ZenHub.
Epics
Epics are a powerful feature that Zenhub adds to Github. They allow you to group related tasks and easily track them from one place. Here is a solid guide to how they work. Here is an example from another City of Austin project.
For ongoing tasks such as a recurring meeting, it may help to create an epic and put the individual instances of the tasks inside it. Here is an example of that type of usage for a task performed for a customer regularly.
Epics do not need estimates assigned to them manually. Instead, the effort is represented by the total of all the story points in the epic's issues.
Ultimately, epics can group whatever makes sense for you and your collaborators. Some people prefer issues with task lists inside them. That's fine as long as the issue doesn't require more effort than we can represent in our estimate scale for a single issue.
Assignees
An issue should be assigned to the person/people who will tackle it. This enables team members to filter down to issues they are responsible for easily.
Learning More
Here are some additional guides for some of our most relied-upon Zenhub functionality:
"Use multi-action to make bulk Issue updates" on this page
The Zenhub docs are super-solid, and we encourage you to peruse them at your leisure. Remember that some functionality—renaming and reordering pipelines themselves, for example—will affect the workspace for the whole team. We're always looking for ways to improve our process, so if you come across an approach or functionality you think is promising, add it to the agenda for our weekly Product Sync or share it in the #atd-product Slack channel!
Last updated
