Skip to main content
Table of Contents

Iterations Naming Conventions - Jira

Ensure seamless tracking of Jira issues in LinearB’s Iterations by following standardized branch and PR naming conventions.

Steven Silverstone
Updated by Steven Silverstone

LinearB’s Iterations automatically links Git activity (branches, pull requests, and commits) to Jira issues. For accurate tracking, teams must follow a consistent naming convention to ensure that Git work is correctly matched to Jira tickets.

By including the Jira issue key in branch names, PR titles, and commits, Iterations can seamlessly associate development work with Jira issues, providing a comprehensive iteration of engineering progress.

Branch and PR Naming Conventions

To enable Iterations to recognize and match Git work to Jira issues, the Jira issue key (e.g., PROJ-123) must be present in branch names and pull requests (PRs).

Recommended Format <Jira-issue-key>-<descriptive-title>

Example Naming Conventions

Jira Issue Key

Task Description

Branch Name

LINB-397

Add repository backfill status

LINB-397-add-repository-backfill-status

LINB-603

Improve Dockerfiles for better layering

LINB-603-improve-dockerfiles-layering

LINB-775

Fix API response handling

LINB-775-fix-api-response-handling

For pull requests (PRs), the Jira issue key should also be included:

  • Example PR TitleAdd repository backfill status (LINB-397)

In this example, both branches (from different repositories) will be matched with the issue above.

How Iterations Matches Git Work to Jira Issues

Iterations automatically scans Git branches, PR titles, and commits for Jira issue keys. The matching algorithm follows these rules:

  1. Branch Names
    • If the branch name includes a valid Jira issue key, Iterations will automatically associate it with the correct Jira issue.
  2. Pull Request (PR) Titles
    • If the PR title contains the Jira issue key, Iterations will match the PR to the issue—even if the branch name does not follow the convention.
  3. Commit Messages
    • Including the Jira issue key in commit messages adds an additional reference for tracking but is not required.

Example Matching Scenario:

  • Jira Issue: "Repository selection - backfill and statuses"
  • Jira Issue Key: "LINB-397"
  • Matching Branch Names:
    • LINB-397-add-repository-backfill-status
    • LINB-397-repository-status-enrichment

Both of these branches (even from different repositories) will be linked to LINB-397 in Iterations.

Handling Issues with Subtasks

If a parent Jira issue has multiple subtasks, Iterations will associate branches and PRs with either:

  • The parent issue key, or
  • The subtask issue keys

Example:

Parent Jira Issue: "Improve Dockerfiles for better layering"

  • Parent Issue Key: LINB-603
  • Subtasks:
    • LINB-775 (Optimize Docker image size)
    • LINB-776 (Improve build caching)
Branch Matching Rules for Subtasks:

Branch Name

Linked Issue in Iterations

LINB-603-improve-dockerfiles-layering

LINB-603 (Parent Issue)

LINB-775-optimize-docker-image-size

LINB-775 (Subtask)

LINB-776-improve-build-caching

LINB-776 (Subtask)

Iterations will match both the parent and subtask issue keys to the parent Jira issue in Iterations view.

Benefits of Using Naming Conventions

✔ Automatic Issue Linking – No need for manual tracking in Iterations.

✔ Improved Iterations Tracking – Ensures all relevant work is reflected in LinearB’s Iterations view.

✔ Better Collaboration – Teams can quickly identify which Git branches and PRs relate to specific Jira issues.

✔ Consistent Workflow – Standardized naming reduces confusion and enforces best practices across repositories.

Best Practices

✔ Always include the Jira issue key when creating a branch.

✔ Use clear, descriptive titles to specify the task being worked on.

✔ Ensure the PR title contains the Jira issue key if the branch name does not follow conventions.

✔ Maintain consistency across teams and repositories.

✔ Educate developers on the importance of naming conventions to ensure Iterations tracks work accurately.

Iterations Naming Conventions – Azure

Iterations

How did we do?

Iterations Naming Conventions - Shortcut

Contact