From df22768a487fe7039d56ccece9da55e24c2781de Mon Sep 17 00:00:00 2001
From: Debian <coder@devbox.lab.kayode.me>
Date: Tue, 18 Aug 2026 17:44:23 +0000
Subject: [PATCH] ci: guide and validate pull request titles

---
 .github/pull_request_template.md | 20 ++++++++++++++++++++
 .github/workflows/pr-title.yml   | 27 +++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 .github/pull_request_template.md
 create mode 100644 .github/workflows/pr-title.yml

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..c660950
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,20 @@
+<!--
+Use a Conventional Commit prefix in the PR title so Release Please knows
+which version to propose:
+
+  fix: correct token refresh       -> patch release (2.1.1 to 2.1.2)
+  feat: add topic management       -> minor release (2.1.1 to 2.2.0)
+  feat!: remove legacy API         -> major release (2.1.1 to 3.0.0)
+
+Other accepted prefixes that do not normally trigger a release:
+  docs:, test:, ci:, chore:, build:, refactor:, perf:, style:, revert:
+Optional scopes are supported, for example: fix(auth): refresh expired tokens
+-->
+
+## Summary
+
+<!-- What changed, and why? -->
+
+## Testing
+
+<!-- How was this tested? -->
diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml
new file mode 100644
index 0000000..eda36db
--- /dev/null
+++ b/.github/workflows/pr-title.yml
@@ -0,0 +1,27 @@
+name: Validate PR title
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - reopened
+
+permissions:
+  contents: read
+
+jobs:
+  conventional-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check Conventional Commit prefix
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          pattern='^(fix|feat|docs|test|ci|chore|build|refactor|perf|style|revert)(\([[:alnum:]_.-]+\))?!?: .+'
+
+          if [[ ! "$PR_TITLE" =~ $pattern ]]; then
+            echo "::error::PR title must start with a Conventional Commit prefix. Examples: 'fix: correct token refresh', 'feat: add topic management', or 'feat!: remove legacy API'."
+            exit 1
+          fi