JiraLens

Welcome to JiraLens, an open-source project fueled by community collaboration. Here are our contribution guidelines.

Encountering challenges or envisioning new features? Share your experiences and thoughts with us through GitHub issues. Your feedback is invaluable in shaping the future of JiraLens!

List of Contents

• Introduction
  • Overview
  • Why JiraLens?
• Features
  • Status Bar Item
  • Inline Message
  • Hover Modal
  • Activity Bar Item
  • Issue Tab
  • Comprehensive Commands
• Extension Setup
  • Jira Host
  • Authentication
    • Jira Cloud
    • Jira Server / Data Center
  • Project Keys
• Data Caching
  • Jira Issue Data
  • Git Blame and Markdown Conversion
• Known Issues

Introduction

Overview

JiraLens is a Visual Studio Code (VS Code) extension tailored for developers seeking deeper insights into their codebase (Extension Marketplace link). It serves as a bridge between your code and the comprehensive information available on Jira pages.

Why JiraLens?

While extensions like GitLens offer valuable insights already, they often fall short of the wealth of information found on Jira. JiraLens seamlessly integrates with Jira pages, providing quick access to crucial details, such as the broader objective, the fix version of the change, and more.

Features

Status Bar Item

Seamlessly open Jira issues in a dedicated VS Code tab or your preferred external browser.

Inline Message

Receive quick information about the committer, relative commit time, Jira issue key, and commit message.

The content of the inline message can be easily configured.

Hover Modal

Gain instant, essential information about the Jira issue while hovering over the inline message.

Activity Bar Item

Experience automatic updates and display of Jira issue content for the active line, ensuring a seamless workflow.

Issue Tab

Effortlessly review multiple Jira issues side by side for comprehensive project management.

Comprehensive Commands

Easily tailor the extension settings to suit your preferences with a simple and intuitive configuration approach.

// Type VS Code commands using: Ctrl/Command + Shift + P
// Available commands:
Set the Jira Host
Set the Jira Email (Jira Cloud only)
Set the API Token / Personal Access Token for Jira Authentication
Add a Jira Project Key
Delete a Jira Project Key
Set Whether to Show the Committer in Inline Message
Set Whether to Show the Relative Commit Time in Inline Message
Set Whether to Show the Jira Issue Key in Inline Message
Set Whether to Show the Commit Message in Inline Message

Extension Setup

To ensure proper functionality, JiraLens requires the Jira host, authentication credentials, and project keys to be configured. Additionally, ensure Jira issue keys are included in commit messages, as they are extracted from there.

You can customize the extension settings either using the VS Code settings editor or by utilizing the commands mentioned above.

Jira Host

If your Jira address begins with https://jira.jiralens.com/..., then set the Jira host as jira.jiralens.com.

Authentication

JiraLens supports both Jira Cloud and Jira Server / Data Center. The authentication method differs between them.

Jira Cloud

Jira Cloud uses email + API token authentication.

1. Set your Jira Email (jiralens.jiraEmail) to the email address associated with your Atlassian account.
2. Generate an API token at id.atlassian.com/manage-profile/security/api-tokens and set it as the API Token (jiralens.jiraBearerToken).

Jira Server / Data Center

Jira Server and Data Center use a Personal Access Token (PAT).

1. Leave Jira Email (jiralens.jiraEmail) empty.
2. Navigate to your Jira profile page, open the Personal Access Tokens tab, and generate a token. Set it as the API Token / Personal Access Token (jiralens.jiraBearerToken).

Project Keys

Refer to this documentation for the definition of Jira issue key and Jira project key. If an issue's key is JRL-123, then its corresponding project key is JRL.

Data Caching

JiraLens caches data locally in memory to keep the inline message, hover modal, and sidebar responsive as you navigate your code.

Jira Issue Data

Fetched Jira issue details are kept in memory and reused for subsequent views of the same issue. By default, a cached issue is considered fresh for 5 minutes before being re-fetched. You can adjust this in VS Code settings via jiralens.jiraCacheTtlSeconds:

• Set a lower value to see more up-to-date issue details at the cost of more network requests.
• Set a higher value to reduce network requests; data may be slightly behind what is on Jira.
• Set to 0 to keep fetched issues for the entire session without ever re-fetching.

The cache is automatically cleared whenever you change your Jira host or authentication credentials, so you will always see data from the correct server with the correct account.

Git Blame and Markdown Conversion

Git blame results and Jira markup conversions are also cached automatically. These caches have no user-facing setting because they manage themselves safely:

• Git blame — Cleared immediately for a file whenever you edit it, so you always see current blame data. There is no risk of stale results because every keystroke that changes a file also clears that file's cached blame entries.
• Markdown conversion — Capped at 200 entries per session. Because the same Jira markup always produces the same output, the result is stored and reused rather than recomputed. 200 entries covers far more than a typical session needs (most developers encounter far fewer than 200 distinct issue descriptions in one sitting), keeping the total memory footprint well under a few megabytes.

If you notice any sluggishness or unexpected memory usage, please open a GitHub issue and describe your experience — it helps us tune the caches further.

Known Issues

1. Some Jira markdowns like colored texts cannot be rendered, when they exist in the content, Jira issue details will stuck at loading.
2. After forward-deleting to pull the next line to the current line, it takes a short while for the inline message to update its position.