ci: enforce conventional commit format on PR titles

.github/workflows/pr-title.yml

@@ -0,0 +1,43 @@
+# PR Title Convention Check
+#
+# Ensures PR titles follow conventional commit format so that
+# squash merges produce commits that semantic-release can analyze.
+#
+# Valid formats:
+#   feat: add new feature
+#   fix(scope): fix bug in scope
+#   docs: update documentation
+#   chore!: breaking change
+
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^.+$
+          subjectPatternError: |
+            The subject (after the type) cannot be empty.
+            Example: "feat: add user authentication"

CLAUDE.md

@@ -42,7 +42,9 @@ helm install team-operator ./dist/chart \
 
 ## Contributing
 
-- Use conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+- **PR titles must follow conventional commit format** (`feat:`, `fix:`, `docs:`, etc.) - this is enforced by CI
+- The repo uses squash merge, so PR title becomes the commit message
+- semantic-release uses commit prefixes for version bumps: `feat:` = minor, `fix:` = patch, `feat!:` = major
 - Run `just test` before committing
 - See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines
 

CONTRIBUTING.md

@@ -124,32 +124,38 @@ just mtest
    - Good: `add-workbench-scaling`, `fix-database-connection`
    - Avoid: `feature/workbench`, `fix/db`
 
-### Commit Message Conventions
+### PR Title Conventions (Required)
 
-We use [Conventional Commits](https://www.conventionalcommits.org/). Each commit message should follow this format:
+We use [Conventional Commits](https://www.conventionalcommits.org/) and **squash merging**. Your PR title becomes the commit message, so it must follow this format:
 
 ```
 <type>(<scope>): <description>
-
-[optional body]
-
-[optional footer]
 ```
 
+> **Important**: PR titles are validated by CI. PRs with non-conforming titles cannot be merged. This is enforced because semantic-release uses commit messages to determine version bumps.
+
 **Types:**
-- `feat:` - New feature
-- `fix:` - Bug fix
+- `feat:` - New feature (triggers minor version bump)
+- `fix:` - Bug fix (triggers patch version bump)
 - `docs:` - Documentation only changes
 - `refactor:` - Code change that neither fixes a bug nor adds a feature
 - `test:` - Adding or correcting tests
-- `chore:` - Changes to the build process or auxiliary tools
+- `build:` - Changes to build system or dependencies
+- `ci:` - Changes to CI configuration
+- `chore:` - Other changes that don't modify src or test files
+- `perf:` - Performance improvements
+- `style:` - Code style changes (formatting, etc.)
+- `revert:` - Reverts a previous commit
+
+**Breaking changes**: Add `!` after the type (e.g., `feat!:`) or include `BREAKING CHANGE:` in the PR body. This triggers a major version bump.
 
 **Examples:**
 ```
 feat(connect): add support for custom resource limits
 fix(workbench): resolve database connection timeout
 docs: update installation instructions
 refactor(controller): simplify reconciliation logic
+feat!: change API response format
 ```
 
 ### Code Style Guidelines
@@ -298,13 +304,18 @@ Include the following in your PR description:
 
 The following checks must pass:
 
+- **PR Title Check** - Title must follow conventional commit format (see above)
 - **Build** - The operator must compile successfully
 - **Unit tests** - All tests must pass
 - **Kustomize** - Kustomization must build without errors
 - **Helm lint** - Chart must pass linting
 - **Helm template** - Templates must render correctly
 - **No diff** - Generated files must be committed
 
+### Merging
+
+This repository uses **squash and merge**. Your PR title becomes the final commit message on `main`. This is why the PR title format is enforced - semantic-release analyzes these commit messages to determine version bumps.
+
 ### Review Expectations
 
 - PRs require at least one approval before merging