Using Echoes
Jul 18, 2023
5 min read
Echoes reports rely on engineering efforts being categorized using your tags of choice. Most tag-based solutions suffer from two problems:
Polluted tag-space and misalignment across teams (e.g., is it “bugs”, “Bugs”, or “defects”?). Echoes solves by centralizing the definition of the taxonomy and keeping labels synchronized across your product-development platforms.
Making tagging simple and assisted enough to guarantee good data quality.
This post focuses on the second point: we cover all the features and conveniences Echoes packs to make tagging a breeze.
Understanding uncategorized efforts
Echoes considers GitHub and GitLab activity as the source of truth for engineering efforts. The implication is that Echoes doesn’t depend on the existence of a ticket for work to be accounted for. Echoes categorization of efforts therefore mainly depends on GitHub pull requests and GitLab merge requests labels being set: when none are set, this piece of work is considered “untagged”.
Untagged efforts in Echoes don’t go unnoticed: they are transparently surfaced in the reports, such that you always know how much of the activity is actually opaque. However, organizations should strive to keep the share of untagged to a minimum to make the most out of the reports, and Echoes packs a lot of features to help them with that.
How Echoes makes tagging a breeze
Cascading JIRA categories
Echoes categorization is done in JIRA using the “Echoes - Intent” custom field.
A JIRA ticket often doesn’t exist in isolation but as part of a broader hierarchy of EPICs, user stories, and tasks. For that reason, Echoes automatically categorizes JIRA issues based on their parent. When an issue is created with a parent, or updated to be attached to a new parent, Echoes examines that parent and copies the content of its “Echoes - Intent” field. Thanks to this feature, a single JIRA EPIC categorized once by setting the “Echoes - Intent” custom field can see this value cascade to dozens of subsequently created user stories and tasks, without any user action.
We will now see how this participates in the ability to automatically categorize GitHub and GitLab contributions thanks to label inference.
Inferring GitHub and GitLab labels from context
Echoes considers GitHub pull requests and GitLab merge requests the source of truth for engineering efforts, but it uses all the information it can find to infer the appropriate labels from the context, including on linked tickets. When a GitHub pull request or GitLab merge request is opened, Echoes searches for anything that resembles a ticket reference. When such a link is found, it automatically applies labels based on the categories found in the referenced ticket or any of its parent.
A core value of Echoes is to embrace whichever process is already in place at the team-level, which is why this inference happens universally across all systems. A GitHub pull request or GitLab merge request may see its label automatically set through its linked GitHub issue, JIRA reference, Linear, or Shortcut issue key. Echoes leverages the categorization already done on the ticket, such that engineers don’t have to categorize some of their contributions themselves.
How much of GitHub pull requests or GitLab merge requests get automatically labeled thanks to this feature entirely depends on a team’s share of contributions being linked to tickets. The benefit of this design is that it makes the most of the process in place, without forcing major changes in habits (for example by mandating tickets from teams who aren’t used to operating this way).
Even teams most rigorous in their process eventually see isolated code contributions not linked to any ticket: the GitHub and GitLab labels checks we will now cover explains how we can make sure that even those get labeled.
Checking for labels in GitHub and GitLab
It is possible to prevent untagged work items from getting into the system by enabling checks at the source. For GitHub, Echoes provides a builtin integration with the Checks feature. When enabled, Echoes will participate in the pull request validation to ensure that the contribution is properly categorized. The built-in GitHub check is disabled by the default to prevent altering the development flow for all teams without notice, and can be enabled on a team-per-team basis.
While GitLab doesn’t provide a comparable feature, Echoes distributes a reusable job to be embedded in your CI pipeline.
These features give each team some agency in the way they want to handle uncategorized items: either by pushing the responsibility to the engineers at the source, or leaving it to the engineering managers to deal with the residue.
Keeping teams in the loop
The best way to get teams engaged in tagging is for them to benefit from the process. Echoes supports role-based access control, which allows to grant read-only access to the reports to anyone within the organization. Even better is to bring the data directly to them.
The Echoes integration for Slack sends a weekly report of the team’s activity into their Slack channel of choice. This very synthetic view of the allocation of efforts on the elapsed week feeds into the team’s retrospective and planning decisions.
Dealing with the residue
After leveraging the features described above, it’s possible that some residual work items remain untagged. Typically, the responsibility of addressing the remaining percent of untagged items will fall on the engineering manager consuming Echoes’ reports.
Categorizing at the source
Echoes makes it possible to (re)categorize work items at any point in time at the source. Changes to a GitHub pull request of GitLab merge requests labels will be taken into account immediately in the reports, and remains possible even after the contribution has been merged.
Categorizing residue from Echoes
Untagged work items can be examined and categorized directly from within Echoes’ interface.
When categorized in Echoes, the corresponding label or field value is also set at the source. This minimizes confusion by keeping all systems in sync, and leaves the possibility of recategorizing the item directly at the source in the future.
Conclusion
Many reporting systems rely on categorization, but their output can only be as good as their inputs. In this post we went over the many ways that Echoes goes over and beyond to make categorizing efforts a breeze. As usual, Echoes strives to make the most of the actions already taken by the teams, embracing the processes and tools that they deem best for them.