From 9f7deee07e8d297edb125214f393207bd8ed80e5 Mon Sep 17 00:00:00 2001
From: Melvin Wang <melvin.mc.wang@gmail.com>
Date: Tue, 17 Mar 2026 15:29:31 -0700
Subject: [PATCH] docs: document and enforce Conventional Commits for PR titles

Update CONTRIBUTING.md with comprehensive Conventional Commits guidance including allowed types, optional scopes, breaking change syntax, and examples. Fix stale master reference to main.

Add lint-pr-title.yaml GitHub Action using amannn/action-semantic-pull-request@v6 to enforce the convention on PR titles with sticky PR comments for contributor-friendly error messages.
---
 .github/workflows/lint-pr-title.yaml | 55 ++++++++++++++++++++++++++++
 CONTRIBUTING.md                      | 46 ++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/lint-pr-title.yaml

diff --git a/.github/workflows/lint-pr-title.yaml b/.github/workflows/lint-pr-title.yaml
new file mode 100644
index 0000000..0205783
--- /dev/null
+++ b/.github/workflows/lint-pr-title.yaml
@@ -0,0 +1,55 @@
+name: Lint PR Title
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR title follows Conventional Commits
+        uses: amannn/action-semantic-pull-request@v6
+        id: lint_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Post error comment on PR
+        if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          message: |
+            Thank you for opening this pull request! 👋
+
+            We require pull request titles to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification, since we use squash-and-merge and the PR title becomes the commit message.
+
+            **Details:**
+
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+            **Examples of valid PR titles:**
+
+            - `feat: add new UMDF sample driver`
+            - `fix: correct build configuration for DriverSync`
+            - `chore: bump wdk dependency versions`
+            - `ci: add ARM64 build support`
+            - `docs: update README with setup instructions`
+            - `refactor!: restructure sample driver layout`
+
+      - name: Delete error comment when resolved
+        if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          delete: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a423238..67cd455 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -75,12 +75,56 @@ Before you submit your Pull Request (PR) consider the following guidelines:
   * Rebase your fork and force push to your GitHub repository (this will update your Pull Request):
 
     ```shell
-    git rebase master -i
+    git rebase main -i
     git push -f
     ```
 
 That's it! Thank you for your contribution!
 
+#### PR Title Format (Conventional Commits)
+
+This repository uses [squash-and-merge](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#squashing-your-merge-commits), so the **PR title becomes the final commit message**. PR titles must follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. This is enforced automatically by CI.
+
+The format is:
+
+```text
+<type>[optional scope]: <description>
+```
+
+**Types** (all lowercase):
+
+| Type | When to use |
+|------|-------------|
+| `feat` | A new feature or user-facing capability |
+| `fix` | A bug fix |
+| `docs` | Documentation-only changes |
+| `style` | Code style/formatting changes (no logic change) |
+| `refactor` | Code restructuring that neither fixes a bug nor adds a feature |
+| `perf` | Performance improvements |
+| `test` | Adding or updating tests |
+| `build` | Build system or dependency changes |
+| `ci` | CI/CD configuration changes |
+| `chore` | Maintenance tasks (dependency bumps, releases, etc.) |
+| `revert` | Reverting a previous commit |
+
+**Scope** is optional. When used, it should be a single noun identifying the affected area (e.g. a sample driver name). Omit the scope for cross-cutting changes. Multiple scopes are not supported.
+
+**Breaking changes** are indicated with `!` after the type/scope:
+
+```text
+refactor!: restructure sample driver layout
+```
+
+**Examples:**
+
+```text
+feat: add new UMDF sample driver
+fix: correct build configuration for DriverSync
+chore: bump wdk dependency versions
+ci: add ARM64 build support
+docs: update README with setup instructions
+```
+
 ## <a name="development"></a> Getting Started with windows-drivers-rs Development
 
 ### Development Requirements