ci(lint): enforce Conventional Commits and branch-name conventions

[parth0025]

Summary

Adds CI enforcement and contributor-facing templates for the conventions documented in BRANCHING.md (PR #208):

• PR titles must follow Conventional Commits (<type>(<scope>): <description>)
• Commit messages must follow Conventional Commits
• Branch names must follow <type>/<kebab-description>
• PR template auto-populates with a useful default (replaces the old "chooser")
• Issue chooser disables blank issues and routes contributors to Discussions / docs / private Security advisories

Step 3 of the open-source repo maintenance baseline initiative (#207 license, #208 branching).

Files changed (6)

File	Status	Purpose
commitlint.config.js	New	11 commit types, lowercase subject, 100-char header limit
.github/workflows/commitlint.yml	New	Lints PR title + every commit in the PR; skips PRs labeled wip or do not merge
.github/workflows/branch-name.yml	New	Validates branch matches <type>/<kebab-description>; exempts release/v*, hotfix-backport/*, dependabot/*, renovate/*
.github/ISSUE_TEMPLATE/config.yml	New	Disables blank issues; links to Discussions, docs, and private Security advisories
.github/pull_request_template.md	Replaced	Default template now has Summary, Type-of-change, Related-issue, Test plan, Screenshots, Breaking-changes, Checklist sections. Specialized templates (bug_fix.md, new_feature.md, refactor.md) remain accessible via ?template= URL params.
package.json	Modified	Adds @commitlint/cli@^19.5.0 + @commitlint/config-conventional@^19.5.0 to devDeps, plus lint:commits script

How to test locally (after merge)

git pull
npm install               # picks up new devDeps
npm run lint:commits      # validate your own commits against the rules

Try opening a draft PR with a malformed title (e.g. Updated stuff) — the new check should fail with a clear error message explaining the expected format.

What contributors will experience

Opening a PR:

• Default PR template is now actually useful (the old chooser is gone)
• 3 new CI checks run on every PR:
  • ✅ PR title (Conventional Commits)
  • ✅ Commit messages (commitlint)
  • ✅ Branch name matches convention

Opening an issue:

• "Open blank issue" is no longer offered — contributors must pick a template (bug / feature / docs)
• Above templates, contact links direct usage questions to docs and Discussions, and security reports to private advisories

Test plan

• After merge, open a test PR with a valid title (e.g., chore: test ci) → all 3 checks should pass
• Open a test PR with an invalid title (e.g., Fixed login) → PR-title check should fail with a clear error
• Open a test PR from a branch with invalid name (e.g., my-cool-fix) → branch-name check should fail
• Apply wip label → PR-title check should be skipped
• Verify the new default PR template renders when opening a PR via the normal "Compare & pull request" button
• Verify specialized templates still work via ?template=bug_fix.md URL
• Verify Issues page no longer offers "Open blank issue" and shows the 4 contact links

Decisions documented (push back during review if any feel wrong)

Decision	Choice	Why
Subject case	Must start lowercase	Conventional Commits norm
Header max length	100 chars	Generous for feat(scope): description patterns
WIP exemption labels	wip, do not merge	Lets in-progress PRs not show red
Pre-commit hook (husky)	NOT added	Keeps scope tight; CI catches it
Bot-branch exemption	dependabot/*, renovate/*	Standard for bot-generated branches

Notes for reviewers

• The PR template references BRANCHING.md, which lands in PR #208. Until docs(branching): add branching strategy and update CONTRIBUTING #208 merges, that link will 404 for a brief window. Self-resolves on merge.
• Existing main.yml CI/deploy workflow is not touched — these new lint jobs run alongside it on PRs.
• Existing specialized PR templates (bug_fix.md, new_feature.md, refactor.md) are not removed — only the default chooser is replaced.
• Existing issue YAML forms (bug_report.yml, feature_request.yml, documentation.yml) are not touched — only config.yml is added alongside them.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Chores
  • Implemented automated validation for branch names and commit messages to enforce consistent development standards.
  • Updated pull request template with structured sections and contributor guidelines for clarity.
  • Configured issue templates to better direct users to relevant resources (documentation, discussions, security advisory).
  • Added development dependencies and scripts to support commit message linting.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f8c219f8-ea2a-43f9-bb4c-a2e02ca16d02

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/conventional-commits-lint

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/pull_request_template.md:
- Around line 27-29: Remove the `hotfix` checklist item from the PR template so
it doesn't encourage using an invalid commit type; edit the block containing the
"Type of change" checklist (the lines showing `feat`, `fix`, `hotfix`) to delete
the `hotfix` entry and instead add a short comment/instruction near the
checklist (e.g., above it) explaining that hotfix branches should still use
`fix` as the commit/PR type; ensure you update the same checklist block in
.github/pull_request_template.md (where the three checkbox items are defined)
and keep the existing wording that the first checked item should match the PR
title prefix.

In @.github/workflows/commitlint.yml:
- Line 66: Replace mutable tag references for GitHub Actions with immutable
commit SHAs: update the uses entries that currently read "actions/checkout@v4"
and "actions/setup-node@v4" to their corresponding commit SHAs (e.g.,
"actions/checkout@<sha>" and "actions/setup-node@<sha>"). Locate the two
occurrences in the workflow (the uses lines) and fetch the latest stable commit
SHAs from the actions' GitHub releases pages before substituting them so the
workflow pins to fixed commits.
- Around line 65-68: The Checkout step ("Checkout (with full history)" using
actions/checkout@v4) currently omits disabling credential persistence; update
that step's with block to include persist-credentials: false so the GITHUB_TOKEN
is not persisted to subsequent steps, e.g., add the persist-credentials: false
key alongside fetch-depth to the actions/checkout@v4 invocation.
- Around line 70-74: The workflow step "Setup Node.js" currently sets
node-version: 22 which conflicts with package.json engines (node: 20.x); update
the "Setup Node.js" step to use node-version: 20 (or 20.x) so the CI runtime
matches package.json and removes EBADENGINE warnings, keeping the rest of that
step (uses: actions/setup-node@v4, cache: npm) unchanged.
- Around line 28-29: The workflow currently references the mutable tag
amannn/action-semantic-pull-request@v5; replace that tag with a specific commit
SHA (e.g., amannn/action-semantic-pull-request@<commit-sha>) to pin the action
for supply chain security. Find the stable SHA for the desired v5 release on the
action's GitHub releases or commit history and update the uses entry in the
Validate PR title step to use that full SHA instead of `@v5`.

In `@package.json`:
- Line 59: The package.json script "lint:commits" currently hardcodes
"origin/staging", which breaks for forks or different base branches; update the
"lint:commits" script to compute the base ref dynamically (e.g., use an
environment variable like COMMITLINT_BASE or derive it via git commands such as
git merge-base or using github.event.pull_request.base.sha when in CI) so the
command uses that dynamic base instead of "origin/staging"; modify the script
entry named "lint:commits" to accept and fallback to a sensible default if the
env var is missing.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3831cb36-9138-4050-b91d-a7e20b4094bc

📥 Commits

Reviewing files that changed from the base of the PR and between 4dbe795 and 61739dc.

📒 Files selected for processing (6)

• .github/ISSUE_TEMPLATE/config.yml
• .github/pull_request_template.md
• .github/workflows/branch-name.yml
• .github/workflows/commitlint.yml
• commitlint.config.js
• package.json