chore: add commit and PR templates with validation (#1)

dreamiurg · claude · web-flow · commit b47524536b2e · 2025-10-21T13:46:18.000-07:00
* chore: add no-commit-to-branch hook to prevent direct commits to master/main Adds pre-commit hook that prevents accidental commits directly to protected branches (master and main). Works in conjunction with GitHub branch protection rules as an additional safeguard. This ensures all changes go through pull requests and proper review workflow. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: add commit and PR templates with validation Adds comprehensive templates and validation for conventional commits: Templates: - .gitmessage: Git commit message template with conventional commit format guide - .github/pull_request_template.md: PR template with clear instructions on title format - scripts/setup-git-hooks.sh: Setup script to configure git templates and pre-commit hooks Validation: - .github/workflows/validate-pr-title.yml: GitHub Action to enforce conventional commit format in PR titles - Uses amannn/action-semantic-pull-request to validate PR titles match semantic-release requirements Documentation: - Updated CLAUDE.md with development setup instructions - Added section explaining PR title enforcement This ensures all PRs follow conventional commit format, which is required for semantic-release to properly version releases. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: simplify PR template to compact format Reduces PR template verbosity while keeping essential information: - Shortened conventional commit format instructions - Simplified type selection checkboxes - Removed unnecessary sections (testing, checklist, etc.) - Kept GitHub Action validation notice 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,22 @@
+<!--
+⚠️ PR TITLE FORMAT: type: description ⚠️
+
+  feat: → minor bump | fix: → patch bump | feat!/fix!: → major bump
+  chore/docs/refactor/test/ci: → no release
+
+A GitHub Action validates your title format.
+-->
+
+## Summary
+
+
+## Type
+- [ ] feat (minor bump)
+- [ ] fix (patch bump)
+- [ ] feat!/fix! (major bump)
+- [ ] chore/docs/refactor/test/ci (no release)
+
+## Changes
+
+-
+-
diff --git a/.github/workflows/validate-pr-title.yml b/.github/workflows/validate-pr-title.yml
@@ -0,0 +1,40 @@
+name: Validate PR Title
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  validate-title:
+    name: Validate PR title follows conventional commit format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Configure which types are allowed (must match semantic-release config)
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            chore
+            ci
+            build
+          # Allow scope in format: type(scope): description
+          requireScope: false
+          # Subject must not be empty
+          subjectPattern: ^.+$
+          subjectPatternError: |
+            The subject "{subject}" found in the PR title "{title}"
+            must not be empty.
+          # Validate the entire title
+          validateSingleCommit: false
+          # Ignore bot PRs (dependabot, etc.)
+          ignoreLabels: |
+            bot
+            dependencies
diff --git a/.gitmessage b/.gitmessage
@@ -0,0 +1,40 @@
+# <type>: <subject>
+#
+# <body>
+#
+# <footer>
+
+# --- COMMIT TYPES ---
+# feat:     New feature (triggers MINOR version bump)
+# fix:      Bug fix (triggers PATCH version bump)
+# docs:     Documentation only changes (no release)
+# style:    Code style/formatting (no release)
+# refactor: Code refactoring (no release)
+# perf:     Performance improvement (triggers PATCH version bump)
+# test:     Adding or updating tests (no release)
+# chore:    Maintenance, dependencies, tooling (no release)
+# ci:       CI/CD configuration (no release)
+# build:    Build system changes (no release)
+#
+# --- BREAKING CHANGES ---
+# Use ! after type for breaking changes: feat!: or fix!:
+# OR add "BREAKING CHANGE:" in footer
+# Breaking changes trigger MAJOR version bump
+#
+# --- RULES ---
+# - Subject line: max 50 chars, imperative mood, lowercase after colon, no period
+# - Body: wrap at 72 chars, explain WHY not WHAT
+# - Footer: reference issues, breaking changes
+#
+# --- EXAMPLES ---
+# feat: add batch peak lookup with rate limiting
+#
+# fix: handle missing elevation data in scraper
+#
+# feat!: restructure CLI to resource-action pattern
+#
+# BREAKING CHANGE: all command names changed to use resource-action pattern
+#
+# docs: update README with new command examples
+#
+# chore: update dependencies to latest versions
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -6,6 +6,10 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
+      # Branch protection
+      - id: no-commit-to-branch
+        args: [--branch, master, --branch, main]
+
       # Formatting and whitespace
       - id: trailing-whitespace
         args: [--markdown-linebreak-ext=md]
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -17,6 +17,17 @@ A Python CLI tool for scraping mountain peak data from PeakBagger.com. Uses Clic
 - **Version Management**: python-semantic-release
 - **Pre-commit**: Configured with multiple hooks
 
+## Development Setup
+
+```bash
+# First time setup - configure git hooks and commit template
+bash scripts/setup-git-hooks.sh
+
+# This will:
+# - Install pre-commit hooks (prevents commits to master/main)
+# - Configure commit message template with conventional commit format
+```
+
 ## Development Commands
 
 ```bash
@@ -43,7 +54,7 @@ uv build
 npx semantic-release --dry-run
 
 # Create release (done automatically via GitHub Actions)
-# Just push to main/master with conventional commit
+# Just merge PR to main/master with conventional commit title
 ```
 
 ## Commit Message Format
diff --git a/scripts/setup-git-hooks.sh b/scripts/setup-git-hooks.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Setup git hooks and commit message template for peakbagger-cli
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+echo "Setting up git hooks and commit message template..."
+
+# Set commit message template
+git config commit.template "${PROJECT_ROOT}/.gitmessage"
+echo "✓ Commit message template configured"
+
+# Install pre-commit hooks
+if command -v pre-commit &> /dev/null; then
+    pre-commit install
+    echo "✓ Pre-commit hooks installed"
+else
+    echo "⚠ pre-commit not found. Install with: uv tool install pre-commit"
+    echo "  Then run: pre-commit install"
+fi
+
+echo ""
+echo "Git configuration complete!"
+echo ""
+echo "Your commits will now use the conventional commit template."
+echo "The template will appear when you run: git commit"
