ci: add PR title validation workflow

[ryderstorm]

Why?

Enforce Conventional Commits specification for PR titles to maintain consistency and enable automated tooling. This is especially important when using squash merge strategy, where the PR title becomes the final commit message that appears in the repository history.

What Changed?

GitHub Actions Workflow

• Added .github/workflows/pr-title-lint.yml using amannn/action-semantic-pull-request@v5
• Validates PR titles against Conventional Commits format on PR events (opened, edited, synchronize, reopened)
• Configured to match existing commitlint types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
• Enforces lowercase description start (conventional commits style)
• Adds helpful sticky comments when validation fails with clear examples
• Auto-deletes comments when PR title is corrected

Documentation Updates

• Updated CONTRIBUTING.md with new "PR Title Format" section
  • Detailed format requirements and examples
  • Guidance on description style (lowercase, imperative mood)
  • Notes on breaking change notation (!)
• Enhanced .github/pull_request_template.md with title format guidance
  • Quick reference at the top of the template
  • Visual indicators (✅/❌) for valid/invalid examples

Additional Notes

Next Steps for Full Enforcement:

1. Enable branch protection rule for main
2. Add "lint-pr-title" to required status checks
3. This will prevent PRs with invalid titles from being merged

Benefits:

• Consistent PR titles that follow the same conventions as commits
• Clear history when using squash merge strategy
• Automated feedback for contributors
• Reduced manual review overhead for title formatting

Testing:
This PR itself follows the conventional commit format and will test the new workflow once merged.

• Linked relevant spec/task IDs: Addresses PR title enforcement need
• Ran tests: N/A (no code changes, only CI/docs)
• Ran linters/hooks: Pre-commit checks pass
• Updated docs or prompts if behavior changed: Yes, updated CONTRIBUTING.md and PR template

Summary by CodeRabbit

• Documentation

  • Added a PR Title Format section requiring Conventional Commits-style titles with valid types, optional scope, examples, and phrasing guidance; updated contributing guide to explain automated title validation.

• Chores

  • Added automated checks that validate PR titles on PR events, post a guidance comment when titles are invalid, and remove the comment once the title is corrected.

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Added a GitHub Actions workflow that lints PR titles against a Conventional Commits-style pattern and posts/removes a sticky PR comment; updated CONTRIBUTING and the PR template to document the required PR title format and examples. No functional application code changed.

Changes

Cohort / File(s)	Summary
GitHub Actions workflow .github/workflows/pr-title-lint.yml	New workflow "Lint PR Title" runs on pull_request (opened, edited, synchronize, reopened). Uses amannn/action-semantic-pull-request@v5 to validate PR titles against allowed types and a subject regex; posts or deletes a sticky comment via marocchino/sticky-pull-request-comment@v2 based on validation.
PR template .github/pull_request_template.md	Added a commented PR title format guidance block with accepted types, examples, and mention of automatic validation (no logic changes).
Contributor guide CONTRIBUTING.md	Added an explicit "PR Title Format" section specifying Conventional Commits-style title pattern, allowed types, examples, subject rules (lowercase, concise, imperative), breaking-change syntax, and note about automated enforcement.

Sequence Diagram(s)

sequenceDiagram
    participant User as User
    participant GH as GitHub
    participant Workflow as pr-title-lint
    participant Sticky as StickyComment

    User->>GH: Open / Edit / Reopen PR
    GH->>Workflow: Trigger workflow (pull_request)

    alt Title valid
        Workflow->>Workflow: Validate title → pass
        Workflow->>Sticky: Delete sticky comment (if present)
        Sticky-->>Workflow: Deletion confirmed
    else Title invalid
        Workflow->>Workflow: Validate title → fail
        Workflow->>Sticky: Post or update sticky comment with error + examples
        Sticky-->>Workflow: Post confirmed
    end

    Workflow-->>GH: Complete run

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through titles, tidy and bright,

"feat: nibble carrots" — now formatted right.
A sticky note appears when the pattern's gone stray,
Fix a line, it hops away.
✨ Small rules, neat hops — happy PR day.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "ci: add PR title validation workflow" accurately reflects the primary technical change in this pull request, which is the addition of a new GitHub Actions workflow (.github/workflows/pr-title-lint.yml) that validates PR titles against the Conventional Commits format. The title is concise, uses the Conventional Commits format being introduced, and avoids vague language or noise. While the changeset also includes documentation updates to CONTRIBUTING.md and the PR template, focusing the title on the main technical contribution is appropriate and expected, as titles need not cover every detail.
Description Check	✅ Passed	The PR description fully adheres to the repository's template structure. It includes a complete "Why?" section explaining the motivation for enforcing Conventional Commits on PR titles, a comprehensive "What Changed?" section detailing the GitHub Actions workflow and documentation updates with specific configuration details, and a thorough "Additional Notes" section covering next steps, benefits, and testing approach. All four checklist items are addressed: spec/task IDs are linked, tests are appropriately marked as N/A for this CI/docs-only change, linters/hooks are confirmed as passing, and documentation updates are documented. The description is clear, detailed, and not vague or generic.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/github-pr-title-enforcement

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3cbe79b and c5c463c.

📒 Files selected for processing (3)

• .github/pull_request_template.md (1 hunks)
• .github/workflows/pr-title-lint.yml (1 hunks)
• CONTRIBUTING.md (2 hunks)

✅ Files skipped from review due to trivial changes (1)

• .github/pull_request_template.md

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/workflows/pr-title-lint.yml

🧰 Additional context used

🪛 LanguageTool

CONTRIBUTING.md

[style] ~141-~141: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 3585 characters long)
Context: ..." or "adds") Breaking changes: Add ! after the type (e.g., feat!: drop Python 3.10 support) If the aut...

(EN_EXCESSIVE_EXCLAMATION)

🔇 Additional comments (2)

CONTRIBUTING.md (2)

104-104: Clear communication of automated title validation requirement.

The addition properly introduces the new enforcement mechanism and prepares readers for the detailed section below.

---

118-144: Excellent documentation structure for PR title requirements.

The section is well-organized, provides clear examples, explains requirements clearly, and documents the breaking-change notation. Alignment with valid types (line 126) and the PR workflow automation is spot-on.

Optional style note: The static analysis tool flagged 5 exclamation marks in this section as potentially excessive. However, the usage is justified—most are necessary technical notation (the ! syntax for breaking changes on line 141 and the auto-retry behavior on line 143). No action required unless you prefer a more subdued tone.

---

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3213088 and 4f055ae.

📒 Files selected for processing (3)

• .github/pull_request_template.md (1 hunks)
• .github/workflows/pr-title-lint.yml (1 hunks)
• CONTRIBUTING.md (2 hunks)

🧰 Additional context used

🪛 LanguageTool

CONTRIBUTING.md

[style] ~134-~134: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 3436 characters long)
Context: ..." or "adds") Breaking changes: Add ! after the type (e.g., feat!: drop Python 3.10 support) If the aut...

(EN_EXCESSIVE_EXCLAMATION)

🪛 markdownlint-cli2 (0.18.1)

CONTRIBUTING.md

117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (5)

CONTRIBUTING.md (1)

113-136: Clear and comprehensive PR title guidance.

The "PR Title Format" section provides excellent documentation with format specification, practical examples (both valid and invalid), and clear conventions. Guidance on imperative mood, lowercase descriptions, and breaking changes aligns well with Conventional Commits standards and contributor needs.

.github/pull_request_template.md (1)

1-14: Well‑designed template header with clear examples.

The PR template header effectively communicates the title format requirement with practical valid and invalid examples that educate contributors before they submit. The HTML comment approach keeps the guidance visible without interfering with template content.

.github/workflows/pr-title-lint.yml (3)

14-39: Semantic PR action configuration looks solid.

The action configuration correctly enforces Conventional Commits with:

• All required types matching documentation
• requireScope: false allowing optional scope
• Pattern ^(?![A-Z]).+$ correctly rejecting uppercase-starting descriptions
• Clear, actionable error messaging

The permissions and trigger events are appropriate.

---

1-72: Excellent coordination across documentation and automation.

The workflow perfectly aligns with CONTRIBUTING.md and the PR template:

• Valid types match exactly across all sources
• Format specification is identical
• Error messaging reinforces documented standards
• Examples in messages match documentation examples

This creates a cohesive contributor experience.

---

42-72: ✓ The workflow output dependency is valid.

The action provides error_message as an output, confirming the workflow's assumptions at lines 43, 53, and 69 are correct. The condition logic—posting a comment when the output is non-null (line 43) and deleting it when null (line 69)—aligns with standard GitHub Actions patterns for error reporting.