The SpecFlow Chart

Inside the Black Box

On most engineering teams, no one has a clear picture of how the code base is changing at any point. An engineer may be familiar with the changes in the parts of the code they personally worked on or code reviewed, but they are typically unaware of other changes going on around them.

Technical leads, who are responsible for a team of engineers often have even less visibility into the details of what everyone is working on, unless they constantly read code, and this is hard to do consistently at any scale. As for non-technical folks, let's not go there. Engineering is a black box for them.

• Say you want to see exactly what code was changed in order to implement a feature that spans branches or repositories, so you can make sure everything that needs to be deployed has been merged.
• Or you suspect certain parts of the code change together consistently whenever features are implemented and you want to understand what these dependencies are, especially when they are non-static: like dependent client and server side changes, cross repository updates etc..
• Maybe you want to understand where you have long lived branches across your code base, because you know they tend to impact delivery flow and add deployment risk.
• Perhaps you are a non-technical manager who wants to know what is happening to that technical debt reduction initiative that kicked off several weeks ago, but has not yet completed and want to discuss the progress on this with a technical lead with data on hand.

There are no easy ways to answers these types of questions about code using the user interfaces of existing DevOps and Work Tracking platforms.

Given our philosophy of empowering teams on the ground with actionable data, a key goal for Polaris is  to give product and engineering teams intuitive and non-technical tools to answer these types of questions on demand with accuracy.

Insight starts with visibility, and much of Polaris is built with this philosophy.

• Technical leads should be able to quickly keep an eye on the overall flow of work through the code base and recognize anomalies and anti-patterns via simple visual cues.
• Non-technical managers should be able to recognize when work might be stuck, and be able to bring data into discussions about work that seems to be churning without end.

In general, we aim to make what happens during implementation less mysterious for everyone, and provide simple and intuitive ways to visualize the work of making software and talk about it as a team.

The SpecFlow Chart is a key component in Polaris for making this happen.

The SpecFlow Chart

The SpecFlow Chart is designed to visualize an arbitrary collection of commits from a certain perspective such as a Value Stream, Contributor, Card or Repository. It shows time on the horizontal axis and one of several analysis dimensions as pivot attributes for the collection on the vertical axis.

In Polaris, a Spec is defined as a card which has commits associated with it. Polaris allows allows commit history to be analyzed along the usual code related perspectives: repositories, branches, files, contributors etc. But focusing on specs facilitates analysis along value related perspectives: cards, card types, features, and epics; and along organizational perspectives: work streams, value streams, and organizations.

Polaris indexes every commit made to a distributed code base, potentially spread across hundreds or thousands of repositories and branches, and organizes them for efficient analysis in real time, along all these perspectives. The underlying time varying representation, called the Ergonometric Graph™, is the foundation of all analysis in Polaris. The SpecFlow Chart is the component that we use across the application for directly visualizing this graph from a variety of perspectives.

It is a fundamental building block in the Polaris App and is used all across the UI.

The Video

The video shows an example of the SpecFlow Chart from the perspective of a single Value Stream, for the prior six months, with pivots for authors, cards, repositories and branches. There are many other possible combinations and periods by which perspectives and pivot attributes can be chosen, and you will see these all across the application.

In this video we show how the chart can be used to answer a variety of questions about the flow of work for the Value Stream, including simple ones like who is working on what, and what is happening to cards in progress, and also more complex ones like recognizing long lived branches, or engineering tasks.

Other perspectives we support today include Cards, Contributors,  Repositories, Organizations, and more will be available in the future.

‍