13min

Developer guide

Introduction

Echoes lets you express the motivation behind pull requests simply through GitHub or GitLab labels. We surface this data into dashboards that shine a light on your work and help management understand the reality of the activity.

We surface no individualized data, no performance metrics, no scores. The goal is to help organizations set clearer goals, improve focus, and offer a better context overall for engineers to deliver their best work. This starts by giving managers an accurate understanding of the reality of the teams.

How to use

TL;DR: use the labels prefixed with echoes/ to tag your pull requests with their purpose. That's all! No need for additional tickets, time-tracking, or switching to a different tool.

These labels are centrally defined in Echoes to represent what matters to your organization, and Echoes keeps them in sync across all of your repositories so you don't have to.

  • echoes/intent: labels express why the pull request exists.
  • echoes/initiative: labels express to what initiative (e.g., feature, or project) the pull request contributes to.
  • echoes/effort: labels express how much effort when into the pull request (M being the default, which corresponds to the average pull request for your team).

Echoes requires pull requests to be tagged with at least one intent or initiative, and optionally with the effort that went into it.

GitHub view of merged pull requests tagged using Echoes
GitHub view of merged pull requests tagged using Echoes

When a GitHub pull request or GitLab merge request references an issue on the same repository or in a third-party issue tracker (e.g., JIRA), Echoes will also automatically follow the link and attempt to find a label it can automatically apply.

Automating labelling

There are certain scenarios where Echoes can infer the intent from the context and will label GitHub pull requests and GitLab merge requests itself:

  • When a GitHub pull request is linked to an issue, or a GitLab merge request is set to automatically close issues, Echoes examines linked issues for labels and applies them automatically. In other words: if your backlog is already categorized using Echoes labels, you're good to go!
  • When Echoes is connected to other πŸ”Œ INTEGRATIONS (such as a JIRA, Linear, or Shortcut instance), it follows these external references to find a label. Echoes may also follow parent links depending on the integration: in the example of JIRA, a single label at the EPIC label will cascade to its user stories, its tasks, down to the pull requests referencing them.

Validating labels

Using GitHub

Echoes integrates with the GitHub check API and can alert you when a pull request is missing the required labels. This check is only enabled for authors that belong to a team from the point of view of Echoes. The check is skipped for example for new employees who haven't yet been added to a team within Echoes, or for open source contributors from the community.

Echoes labels check integration in GitHub checks
Echoes labels check integration in GitHub checks

Using GitLab

Echoes offers a reusable GitLab job to do the labels check. Include the corresponding yaml file and add this job to your stages to enable it:

Diff
|

FAQ

Q: What if I don't know which label to set for a particular pull request? Leave it blank! It's better to have some untagged items rather than randomly tagged pull requests.

Q: Can I add a new echoes/ label from GitHub if needed? No: Echoes will regularly reconcile labels on repositories with its configuration and your label will get deleted. New labels must be added from Echoes configuration and will then get published on all repositories.

Q: Will it make any difference on results if I send fewer/more, or smaller/larger pull requests? No: Echoes doesn't look at the diff, nor at the absolute number of pull requests. You can continue contributing exactly as you're used to, with the minor change of adding labels!

Q: Can I get access to the dashboard? Yes, you can ask the Echoes administrator for your organization to create an invite and share a signup link. This will give you access to the dashboard, as well as to an individual report highlighting your contributions over time (which nobody but yourself has access to).

Q: What happens if a commit appears in multiple pull requests? Echoes keeps tracks of commits and can recognize when a same commit appears in the context of different pull request. One very common scenario is when changes are submitted against a staging branch, and this staging branch gets merged to main to trigger a release: Echoes will account for the commits when they are first introduced to staging.

ο»Ώ

Updated 09 Jun 2022
Did this page help you?
Yes
No