website logo
⌘K
🤗Welcome
🚀Engineering success
🧭Alignment
⚡Delivery
💗Health
🏷️Categorizing work
Dimensions
Initiatives
Teams
🎯Measuring success
Defining targets
Delivery performance
🔌Data connections
🔔Automated reports
🎓Reference
👤Administration
📅Changelog
Docs powered by archbee 
website logo
Sign upLogin

JIRA

13min

Purpose

Echoes can connect to your JIRA Cloud instance and help you tag JIRA issues with their intended outcomes and initiatives they contribute to. This allows you to express the purpose of work during the planning process in JIRA and have related code contributions inherit these annotations, therefore reducing the labelling effort for engineers.

Example of labels inheritance
Example of labels inheritance


In the example above, a pull request references JIRA sub-task JIRA-3 in its title. Echoes successively inspects JIRA-3, its parent story JIRA-2, and the parent EPIC JIRA-1, collecting all values of the intent field along the path. It finds an intent on the EPIC and applies the corresponding label to the pull request. This required a single tag in JIRA, and no developer action.

Installation and configuration

Echoes JIRA integration consists of an Atlassian Connect app which only requires read permissions to your JIRA instance. Installation is done through Echoes’ integrations settings.

Echoes integrations
Echoes integrations


The connect button asks for the base URL of your JIRA instance (e.g., https://mycompany.atlassian.net) and take you to the installation page on the JIRA marketplace. Once installed, you will see custom fields appear on your JIRA instance (you can filter fields on "Echoes" to find them easily).

JIRA custom field administration
JIRA custom field administration


The custom fields must be manually added to screens!

Echoes creates the "Echoes - Intent" and "Echoes - Effort" custom fields on your JIRA instance but doesn’t add them to any screens by default in order to leave this decision up to the JIRA administrator.

Follow the JIRA documentation to add the custom fields to the screens of your choice.

Associating Echoes custom fields to JIRA screens
Associating Echoes custom fields to JIRA screens


Enforcing categorization

The "Echoes - Intent" custom field can be made required on issues to enforce categorization. Refer to JIRA field configuration documentation to mark the field as required.

JIRA field configuration
JIRA field configuration


How to use

Once connected to your JIRA Cloud instance, Echoes creates and manages two custom fields:

  • The "Echoes - Intent" multi-select field is populated with the outcomes and initiatives configured in Echoes, and is automatically updated as the configuration changes over time.
  • The "Echoes - Effort" single-select field is populated with a simple t-shirt size scale.
Creating a JIRA issue with the custom field
Creating a JIRA issue with the custom field


Automating code contributions labeling

The "Echoes - Intent" field is used to express the intended outcomes or initiative motivating a JIRA issue (either task, story, or EPIC). Opening a GitHub pull request or GitLab merge request which references an issue (either in the pull request title, the message headline of one of its commits, or the branch name) will automatically apply labels for the corresponding intents without any action from the author.

Labels automatically inherited from a JIRA referenced issue
Labels automatically inherited from a JIRA referenced issue


Labeling behavior details

  • Labels are only applied when a pull request is opened, edited, or reopened. Changing the intent on a JIRA ticket will not change the labels on a previously opened pull request.
  • The automation only adds more labels and never removes previously existing labels from the pull request.

Accounting for non-coding activity

You may want to account in Echoes for efforts which contribute to goals but don't materialize as contributions in the source code manager. For example, this could be an engineer spending one day investating a production issue, or provisioning resources in your cloud provider. This is the purpose of the "Echoes - Effort" custom field.

Using the "Echoes - Effort" custom field to account non-coding activities
Using the "Echoes - Effort" custom field to account non-coding activities


When an issue gets resolved, Echoes accounts for the effort as set in "Echoes - Effort". This field is empty by default, which means that JIRA issues are generally only accounted for through efforts arising from linked GitHub pull requests and GitLab merged requests. Attributing a non-zero value to the "Echoes - Effort" custom field will confer the issue a weight of its own, using the same t-shirt size scale used for pull requests and merge requests.

Usage of the Completion field on JIRA

In addition to the above configuration, to make the best use of Echoes, we recommend that you follow Atlassian recommendations regarding the usage of the "Completion field" on your JIRA issues. Echoes uses the Completion field as primary source of information to evaluate whether a JIRA issue is considered "open", or "closed".

FAQ

Are JIRA issues' parent or EPIC links followed?

Echoes follows both the “Epic Link” and "parent" fields. A GitHub pull request which references a JIRA issue will get automatically labeled with all tags carried by the issue, its parent (if any), and its EPIC (if any).

What is the purpose of the "Echoes - Effort" field?

The "Echoes - Effort" custom field allows to attribute a non-zero effort to a JIRA ticket. A ticket doesn't contribute to Echoes reported efforts by default. The reason for this is that Echoes measures effort from GitHub pull requests and GitLab merge requests, and considers tickets to be a description of efforts rather than efforts themselves.

There are however cases where engineers spend efforts on tasks which do not lead to changes in GitHub or GitLab (e.g., investigating a production issue, or working on architecture plans). When such tasks exist as JIRA tickets, setting a non-empty value for the "Echoes - Effort" field allows to account for these efforts.



Updated 25 May 2023
Did this page help you?
Yes
No
PREVIOUS
Issue trackers
NEXT
Linear
Docs powered by archbee 
TABLE OF CONTENTS
Purpose
Installation and configuration
The custom fields must be manually added to screens!
Enforcing categorization
How to use
Automating code contributions labeling
Labeling behavior details
Accounting for non-coding activity
Usage of the Completion field on JIRA
FAQ
Are JIRA issues' parent or EPIC links followed?
What is the purpose of the "Echoes - Effort" field?