Iterations Naming Conventions - Jira

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

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

• Example PR Title: Add 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:

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.

Related Links

Iterations Naming Conventions – Azure

Iterations