From 2bc8a5f77b96cedf975f1a13241ba74c4bc8598e Mon Sep 17 00:00:00 2001 From: Melvin Wang Date: Mon, 16 Mar 2026 16:45:33 -0700 Subject: [PATCH] docs: document and enforce Conventional Commits for PR titles Update CONTRIBUTING.md with comprehensive Conventional Commits guidance including allowed types, optional crate-name scopes, breaking change syntax, and examples. 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 | 66 ++++++++++++++++++++++++++++ CONTRIBUTING.md | 63 +++++++++++++++++++++++--- 2 files changed, 123 insertions(+), 6 deletions(-) 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 000000000..45a5c1119 --- /dev/null +++ b/.github/workflows/lint-pr-title.yaml @@ -0,0 +1,66 @@ +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 }} + with: + scopes: | + cargo-wdk + wdk + wdk-alloc + wdk-build + wdk-macros + wdk-panic + wdk-sys + requireScope: false + + - 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:** + + - `fix: correct typo in wdk-build` + - `feat: add support for UMDF driver templates` + - `chore: bump serde from 1.0.219 to 1.0.228` + - `fix(cargo-wdk): resolve path construction issue` + - `ci: add ARM64 Windows runner support` + - `docs: update README with new installation steps` + - `refactor!: drop support for WDK 10.0.22621` + + - 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 f6d4fc770..dd4cdd652 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,25 +62,76 @@ You can file new issues by providing the above information at the corresponding Before you submit your Pull Request (PR) consider the following guidelines: -* Search the repository () for an open or closed PR +* Search the [repository]() for an open or closed PR that relates to your submission. You don't want to duplicate effort. -* Make your changes in a new git fork: +* Fork the repository and make changes on your fork locally. -* Commit your changes using a descriptive commit message -* Push your fork to GitHub: -* In GitHub, create a pull request +* Commit your changes using a descriptive commit message. +* Push your commit to your forked repository. +* In GitHub, create a pull request to merge your fork to `main`. * If we suggest changes then: * Make the required updates. * 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 +[optional scope]: +``` + +**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** (optional): A single noun in parentheses identifying the affected area. For this repository, crate names are the natural scopes: + +* `cargo-wdk`, `wdk`, `wdk-build`, `wdk-sys`, `wdk-macros`, `wdk-alloc`, `wdk-panic` + +Scope should be **omitted** when a change is cross-cutting or doesn't map to a single crate. Multiple scopes are not supported by the spec — if a change touches multiple crates, just leave the scope off. + +**Breaking changes** are indicated with `!` after the type/scope: + +```text +refactor!: drop support for WDK 10.0.22621 +feat(wdk-sys)!: redesign FFI binding generation +``` + +**Examples:** + +```text +feat: add dbg! macro to wdk +fix: correct path construction in wdk-build +chore: bump serde from 1.0.219 to 1.0.228 +fix(cargo-wdk): resolve architecture detection issue +ci: add ARM64 Windows runner support +docs: update README with new installation steps +refactor!: bump to Rust 2024 Edition +``` + ## Getting Started with windows-drivers-rs Development ### Development Requirements