Message-Id: <20250717074745.8333-1-ignacio.pena87@gmail.com>
Date: Thu, 17 Jul 2025 03:47:45 -0400
From: Ignacio Peña <ignacio.pena87@...il.com>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Ignacio Pena <ignacio.pena87@...il.com>
Subject: [PATCH] Documentation: Add patch-validator to dev-tools

From: Ignacio Pena <ignacio.pena87@...il.com>

Add documentation for patch-validator, a comprehensive tool that helps
kernel contributors validate their patches before submission. This tool
catches common mistakes that frequently lead to patch rejections,
improving the quality of submissions and reducing maintainer workload.

The validator performs 21+ automated checks including:
- Patch format validation (subject line, changelog placement)
- DCO compliance and licensing verification  
- checkpatch.pl integration with enhanced reporting
- Build impact analysis and testing recommendations
- Common novice pattern detection
- Git configuration validation

Also includes companion tools for finding first contributions,
testing patches safely, and validating patch series.

Link: https://github.com/ipenas-cl/kernel-patch-validator
Signed-off-by: Ignacio Pena <ignacio.pena87@...il.com>
---
 Documentation/dev-tools/index.rst           |   1 +
 Documentation/dev-tools/patch-validator.rst | 287 +++++++++++++++++++
 2 files changed, 288 insertions(+)
 create mode 100644 Documentation/dev-tools/patch-validator.rst

diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 000000000000..111111111111 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst
    kunit/index
    ktap
    checkpatch
+   patch-validator
    coccinelle
    sparse
    kcov
diff --git a/Documentation/dev-tools/patch-validator.rst b/Documentation/dev-tools/patch-validator.rst
new file mode 100644
index 000000000000..222222222222
--- /dev/null
+++ b/Documentation/dev-tools/patch-validator.rst
@@ -0,0 +1,287 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Kernel Patch Validator
+========================
+
+The kernel patch validator is a comprehensive tool that helps contributors
+validate their patches before submission to kernel mailing lists. It catches
+common mistakes that frequently lead to patch rejections, improving submission
+quality and reducing maintainer workload.
+
+Installation
+============
+
+The validator is available at:
+https://github.com/ipenas-cl/kernel-patch-validator
+
+Quick installation::
+
+        $ git clone https://github.com/ipenas-cl/kernel-patch-validator.git ~/kernel-patch-validator
+        $ cd ~/kernel-patch-validator
+        $ chmod +x scripts/*.sh
+
+        # Optional: Add to PATH
+        $ echo 'export PATH="$PATH:$HOME/kernel-patch-validator/scripts"' >> ~/.bashrc
+        $ source ~/.bashrc
+
+Quick Start
+===========
+
+Validate a single patch::
+
+        $ git format-patch -1
+        $ validate-patch.sh 0001-your-patch.patch
+
+Validate a patch series::
+
+        $ git format-patch -3 --cover-letter
+        $ validate-series.sh .
+
+Find contribution opportunities::
+
+        $ find-bugs.sh
+
+Core Features
+=============
+
+The validator performs 21+ automated checks:
+
+Format Validation
+-----------------
+* Future date detection (system clock issues)
+* Signed-off-by presence and format (DCO compliance)
+* Subject line format ``[PATCH] subsystem: lowercase description``
+* Version changelog placement after ``---`` marker
+* Fixes: tag format with 12+ character SHA
+* Cc: stable format validation
+
+Code Quality
+------------
+* checkpatch.pl --strict integration
+* Patch apply verification
+* Build impact analysis
+* Single logical change verification
+* Commit message quality assessment
+
+Best Practices
+--------------
+* Novice pattern detection (console output, TODOs)
+* Git configuration validation
+* Debug configuration mentions
+* Testing information requirements
+* Static analysis recommendations
+* Performance impact assessment for large changes
+
+Additional Tools
+================
+
+test-patch.sh
+-------------
+Safe patch testing workflow::
+
+        $ test-patch.sh 0001-my-patch.patch
+
+* Creates temporary test branch
+* Applies and compiles patch
+* Runs sparse/smatch if available
+* Automatically cleans up
+
+find-bugs.sh
+------------
+Automated contribution finder::
+
+        $ find-bugs.sh
+
+* Detects spelling/grammar errors
+* Finds checkpatch issues
+* Identifies missing .gitignore entries
+* Suggests debug configurations
+* Integrates syzbot reports
+
+contribution-checklist.sh
+-------------------------
+Interactive readiness assessment::
+
+        $ contribution-checklist.sh
+
+* Evaluates community engagement
+* Verifies technical setup
+* Provides personalized action plan
+* Scores knowledge areas
+
+validate-series.sh
+------------------
+Patch series validation::
+
+        $ validate-series.sh directory/
+
+* Validates numbering sequence
+* Checks cover letter
+* Ensures version consistency
+* Tests apply order
+
+Common Workflows
+================
+
+First Contribution
+------------------
+1. Find an issue to fix::
+
+        $ find-bugs.sh
+        ✓ Found 23 spelling errors
+        ✓ Found 45 checkpatch issues in staging
+
+2. Make your fix and validate::
+
+        $ git format-patch -1
+        $ validate-patch.sh 0001-fix-spelling.patch
+
+3. Send if all checks pass::
+
+        $ git send-email --to="maintainer@...mple.com" 0001-fix-spelling.patch
+
+Patch Series (v2)
+-----------------
+1. Create series with cover letter::
+
+        $ git format-patch -3 --cover-letter -v2
+
+2. Validate entire series::
+
+        $ validate-series.sh .
+
+3. Add changelog after --- in each patch::
+
+        ---
+        v2: Split into separate patches per maintainer feedback
+
+         drivers/staging/driver.c | 10 +++++-----
+
+Common Issues Detected
+======================
+
+Date Problems
+-------------
+The validator catches future dates (2025 bug)::
+
+        ✗ Date Check - Patch contains future date (2025)
+
+Fix: Correct system time before generating patches.
+
+Missing Changelog
+-----------------
+v2+ patches must document changes::
+
+        ✗ Version Changelog - v2+ patches must have changelog after --- marker
+
+Example fix::
+
+        Subject: [PATCH v2] staging: fix checkpatch warnings
+        
+        Fix multiple checkpatch warnings in driver.
+        
+        Signed-off-by: Your Name <you@...mple.com>
+        ---
+        v2: Split into separate patches as requested
+        
+         drivers/staging/driver.c | 20 ++++++++++----------
+
+Multiple Changes
+----------------
+Patches doing multiple things::
+
+        ⚠ Single Purpose - Patch might be doing multiple things
+
+Solution: Split into separate patches, one per logical change.
+
+Integration with Kernel Workflow
+================================
+
+The validator complements existing kernel tools:
+
+Before checkpatch.pl
+--------------------
+* Catches format issues checkpatch might miss
+* Validates changelog placement
+* Checks git configuration
+
+With get_maintainer.pl
+----------------------
+* Reminds to use get_maintainer.pl
+* Shows suggested recipients
+* Validates recipient format
+
+Testing Integration
+-------------------
+* Suggests appropriate test commands
+* Checks for testing documentation
+* Validates CI mentions for complex patches
+
+Best Practices
+==============
+
+1. **Always validate before sending** - Takes 30 seconds, saves hours
+2. **Fix all errors** - Don't send patches with validation errors  
+3. **Consider warnings** - They indicate areas for improvement
+4. **Use companion tools** - find-bugs.sh helps locate good first issues
+5. **Document testing** - Include what/how you tested
+
+Tips for New Contributors
+=========================
+
+Start Small
+-----------
+* Use find-bugs.sh to locate simple fixes
+* Focus on staging drivers initially
+* Fix one issue per patch
+
+Common Mistakes to Avoid
+------------------------
+* Don't mix functional and style changes
+* Don't send patches from the future (check system date)
+* Don't forget version changelogs on v2+
+* Don't skip testing ("compile tested only" = lazy)
+
+Follow the Process
+------------------
+1. Find issue with find-bugs.sh
+2. Create fix and commit
+3. Generate patch with git format-patch
+4. Validate with validate-patch.sh
+5. Find maintainers with get_maintainer.pl
+6. Send with git send-email
+
+Example Output
+==============
+
+Successful validation::
+
+        $ validate-patch.sh 0001-staging-fix-typo.patch
+        ======================================
+           KERNEL PATCH VALIDATOR v1.0
+        ======================================
+        
+        === Basic Patch Checks ===
+        ✓ Date Check
+        ✓ Signed-off-by (DCO)
+        ✓ Subject Format
+        ✓ Version Changelog (v1 patch)
+        
+        === Code Style Checks ===
+        ✓ checkpatch.pl
+        ✓ Patch Apply
+        ⚠ Build Test Required
+        
+        ======================================
+                  VALIDATION SUMMARY
+        ======================================
+        ⚠ WARNINGS: 1 issues found (patch is sendable but could be improved)
+
+Contributing to the Validator
+=============================
+
+The validator is open source and welcomes contributions:
+https://github.com/ipenas-cl/kernel-patch-validator
+
+Each check is based on real rejection feedback from kernel maintainers.
-- 
2.39.5

Powered by blists - more mailing lists