ci: enforce Conventional Commits PRs

Author: erikgb

.github/workflows/lint-pr.yaml

@@ -0,0 +1,57 @@
+name: "Lint PR"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@0723387faaf9b38adef4775cd42cfd5155ed6017 # v5.5.3
+        id: lint_pr_title
+        with:
+          # Ensure the subject doesn't start with an uppercase character.
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            Please ensure the subject in the pull request title ("{subject}")
+            doesn't start with an uppercase character.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.1
+        # When the previous steps fail, the workflow would stop. By adding this
+        # condition you can continue the execution with the populated error message.
+        if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        with:
+          header: pr-title-lint-error
+          message: |
+            Hey there and thank you for opening this pull request! :wave:
+
+            We require pull request titles to follow the
+            [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/)
+            and it looks like your proposed title needs to be adjusted.
+            
+            While the specification does not require a specific casing, it recommends being consistent.
+            We use the pull request title in automated release changelog updates, and would like our
+            changelogs to look nice.
+
+            Details:
+            
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.1
+        with:
+          header: pr-title-lint-error
+          delete: true

CONTRIBUTING.md

@@ -18,11 +18,13 @@ interact with the project and how to get involved in development as smoothly as
 
 These things will make a PR more likely to be accepted:
 
+- should address a single concern or task
+- avoid bundling unrelated changes
 - a well-described requirement
 - tests for new code
 - tests for old code!
 - new code and tests follow the conventions in old code and tests
-- a good commit message (see below)
+- a good PR title and description (see below)
 - all code must abide by [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
 - names should abide by [What's in a name](https://talks.golang.org/2014/names.slide#1)
 - code must build on both Linux and Darwin, via plain `go build`
@@ -31,8 +33,19 @@ These things will make a PR more likely to be accepted:
 
 In general, we will merge a PR once at least one maintainer has endorsed it. For substantial changes, more people may become involved, and you might get asked to resubmit the PR or divide the changes into more than one PR.
 
-## Format of the Commit Message
+## Format of the pull request
 
-Limit the subject to 50 characters and write as the continuation of the sentence "If applied, this commit will ..."
-Explain what and why in the body, if more than a trivial change; wrap it at 72 characters.
-The [following article](https://cbea.ms/git-commit/#seven-rules) has some more helpful advice on documenting your work.
+This project enforces that your pull request title match the
+[Conventional Commits specification](https://conventionalcommits.org).
+When the PR is merged, the full PR changeset will be squashed into a single
+commit on the default branch using the PR title as the commit message.
+While this approach might surprise some, this is done to simplify the release
+process including generating (good) release notes.
+
+The commit message on the default branch will automatically include a reference
+back to the PR, so please explain what and why in the PR description.
+
+Each pull request should address a single concern or task.
+Avoid bundling unrelated changes into one PR, as it can make the review process
+more challenging and less efficient. Keeping PRs focused helps reviewers
+understand the purpose and context of the changes.

README.md

@@ -4,6 +4,7 @@
 [![LICENSE](https://img.shields.io/github/license/weaveworks/weave-gitops)](https://github.com/weaveworks/weave-gitops/blob/master/LICENSE)
 [![Contributors](https://img.shields.io/github/contributors/weaveworks/weave-gitops)](https://github.com/weaveworks/weave-gitops/graphs/contributors)
 [![Release](https://img.shields.io/github/v/release/weaveworks/weave-gitops?include_prereleases)](https://github.com/weaveworks/weave-gitops/releases/latest)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fweaveworks%2Fweave-gitops.svg?type=shield&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fweaveworks%2Fweave-gitops?ref=badge_shield&issueType=license)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fweaveworks%2Fweave-gitops.svg?type=shield&issueType=security)](https://app.fossa.com/projects/git%2Bgithub.com%2Fweaveworks%2Fweave-gitops?ref=badge_shield&issueType=security)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/7820/badge)](https://www.bestpractices.dev/projects/7820)