YTDB-509: Add automation to prefix commits and PR titles with issue number (#621)

#### Motivation:

When working on issue-related branches, developers often forget to
include the issue number in commit messages and PR titles, making it
harder to trace changes back to their associated issues. This PR adds
automation and documentation to ensure consistent formatting across the
team, improving traceability and reducing manual effort.

#### Changes:

**Git hook** (`prepare-commit-msg` in `.githooks/` directory):
- Matches branches starting with `YTDB` prefix (case-insensitive)
followed by optional separator and numbers (e.g., `ytdb-509`,
`YTDB_123`, `ytdb509`)
- Automatically prepends `YTDB-<number>: ` to commit messages
- Normalizes output to uppercase `YTDB` with `-` separator
- Skips prefixing if the issue number already exists anywhere in the
message (case-insensitive check)
- Ignores merge, squash, and amend commits to avoid interference with
git workflows
- Handles detached HEAD state gracefully

**GitHub Action** (`.github/workflows/pr-title-prefix.yml`):
- Triggers on PR open, edit, and synchronize events targeting `develop`
branch
- Automatically prefixes PR title with `YTDB-<number>:` based on branch
name
- Skips if the issue prefix already exists in the title
(case-insensitive check)

**PR template** (`.github/pull_request_template.md`):
- Added guidance to prefix PR titles with issue number (e.g., `YTDB-123:
Your PR title`)

#### Setup:

Developers need to enable the git hook by running:
```bash
git config core.hooksPath .githooks
```

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: andrii0lomakin

.githooks/prepare-commit-msg

@@ -0,0 +1,51 @@
+#!/bin/bash
+#
+# Git hook to automatically add issue prefix to commit messages
+# based on the branch name pattern: ytdb/YTDB + optional non-letter + numbers (case-insensitive)
+# Examples: ytdb-509-feature -> "YTDB-509: <message>"
+#           YTDB509-feature  -> "YTDB-509: <message>"
+
+COMMIT_MSG_FILE=$1
+COMMIT_SOURCE=$2
+
+# Only process regular commits (not merges, amends with existing message, etc.)
+# Allow: no source (regular commit), "message" (-m flag), "template"
+if [ "$COMMIT_SOURCE" = "merge" ] || [ "$COMMIT_SOURCE" = "squash" ] || [ "$COMMIT_SOURCE" = "commit" ]; then
+    exit 0
+fi
+
+# Get current branch name
+BRANCH_NAME=$(git symbolic-ref --short HEAD 2>/dev/null)
+
+# Exit if not on a branch (detached HEAD)
+if [ -z "$BRANCH_NAME" ]; then
+    exit 0
+fi
+
+# Extract issue prefix: "ytdb" (case-insensitive) followed by optional non-letter followed by numbers
+# Pattern explanation: ^(ytdb)([^a-zA-Z0-9]?)([0-9]+)
+# - ^            : start of string
+# - ytdb         : literal "ytdb" prefix (matched case-insensitively)
+# - [^a-zA-Z0-9]?: optional single non-alphanumeric character (separator like - or _)
+# - [0-9]+       : one or more digits
+BRANCH_NAME_LOWER=$(echo "$BRANCH_NAME" | tr '[:upper:]' '[:lower:]')
+if [[ $BRANCH_NAME_LOWER =~ ^(ytdb)([^a-zA-Z0-9]?)([0-9]+) ]]; then
+    # Normalize the prefix: always use uppercase 'YTDB' and '-' as separator
+    ISSUE_PREFIX="YTDB-${BASH_REMATCH[3]}"
+    FULL_PREFIX="$ISSUE_PREFIX: "
+
+    # Read current commit message
+    COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+    # Check if the issue number already exists anywhere in the message (case-insensitive)
+    ISSUE_PREFIX_LOWER=$(echo "$ISSUE_PREFIX" | tr '[:upper:]' '[:lower:]')
+    COMMIT_MSG_LOWER=$(echo "$COMMIT_MSG" | tr '[:upper:]' '[:lower:]')
+
+    if [[ ! "$COMMIT_MSG_LOWER" =~ $ISSUE_PREFIX_LOWER ]]; then
+        # Prepend the issue prefix to the commit message
+        echo -n "$FULL_PREFIX" > "$COMMIT_MSG_FILE"
+        echo "$COMMIT_MSG" >> "$COMMIT_MSG_FILE"
+    fi
+fi
+
+exit 0

.github/pull_request_template.md

@@ -1,3 +1,7 @@
+#### PR Title:
+
+If this PR is related to an issue, prefix the title with the issue number (e.g., `YTDB-123: Your PR title`).
+
 #### Motivation:
 
 A clear and concise explanation of why this change is necessary and what problem it solves.

.github/workflows/pr-title-prefix.yml

@@ -0,0 +1,56 @@
+name: PR Title Issue Prefix
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+    branches: [develop]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  add-issue-prefix:
+    name: Add issue prefix to PR title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check and update PR title
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const branchName = context.payload.pull_request.head.ref;
+            const currentTitle = context.payload.pull_request.title;
+
+            // Match YTDB prefix (case-insensitive) with optional separator followed by numbers
+            // Pattern: ytdb/YTDB + optional non-alphanumeric + digits
+            const branchMatch = branchName.toLowerCase().match(/^(ytdb)[^a-z0-9]?(\d+)/);
+
+            if (!branchMatch) {
+              console.log(`Branch "${branchName}" does not match YTDB pattern. Skipping.`);
+              return;
+            }
+
+            const issueNumber = branchMatch[2];
+            const issuePrefix = `YTDB-${issueNumber}`;
+
+            // Check if the issue prefix already exists in the title (case-insensitive)
+            const titleLower = currentTitle.toLowerCase();
+            const prefixLower = issuePrefix.toLowerCase();
+
+            if (titleLower.includes(prefixLower)) {
+              console.log(`PR title already contains "${issuePrefix}". Skipping.`);
+              return;
+            }
+
+            // Update PR title with the prefix
+            const newTitle = `${issuePrefix}: ${currentTitle}`;
+
+            await github.rest.pulls.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+              title: newTitle
+            });
+
+            console.log(`Updated PR title from "${currentTitle}" to "${newTitle}"`);