[PATCH] Documentation: Add patch-validator to dev-tools

[PATCH] Documentation: Add patch-validator to dev-tools

[Ignacio Peña]

From: Ignacio Pena <ignacio.pena87@gmail.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@gmail.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@example.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@example.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

Re: [PATCH] Documentation: Add patch-validator to dev-tools

[Jonathan Corbet]

Ignacio Peña <ignacio.pena87@gmail.com> writes:

> From: Ignacio Pena <ignacio.pena87@gmail.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@gmail.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

Interesting ... overall, we don't generally have detailed documentation
for out-of-tree utilities, though there isn't necessarily any reason why
we couldn't.  But I'm curious as to why you haven't submitted the tool
itself?

Thanks,

jon

Re: [PATCH] Documentation: Add patch-validator to dev-tools

[Ignacio Peña]

On Thu, Jul 17, 2025 at 09:38:00AM -0600, Jonathan Corbet wrote:
> Interesting ... overall, we don't generally have detailed documentation
> for out-of-tree utilities, though there isn't necessarily any reason why
> we couldn't.  But I'm curious as to why you haven't submitted the tool
> itself?

That's a great question! I kept it external for a few reasons:

First, I'm still pretty new to kernel development and wanted the freedom
to iterate quickly as I learn what checks are actually useful. Being 
external means I can push updates immediately when someone points out
a new common mistake (like Greg just did with the date check!).

Second, I wrote everything in bash for simplicity, which probably isn't
the best fit for the kernel's scripts/ directory. Plus, as Greg mentioned
in his reply, many of these checks really belong in checkpatch.pl rather
than a separate tool.

So my plan now is to work on patches for checkpatch.pl to add the most
useful checks there (where they belong), while keeping the workflow 
helpers as an external toolkit.

Given this direction, would you prefer I withdraw this documentation 
patch? I'm happy either way - just thought it might help other newcomers
in the meantime, but I totally understand if you'd rather wait until
the checks are properly integrated into checkpatch.pl.

Thanks for reviewing this!

Thanks,
Ignacio

Re: [PATCH] Documentation: Add patch-validator to dev-tools

[Jonathan Corbet]

Ignacio Peña <ignacio.pena87@gmail.com> writes:

> On Thu, Jul 17, 2025 at 09:38:00AM -0600, Jonathan Corbet wrote:
>> Interesting ... overall, we don't generally have detailed documentation
>> for out-of-tree utilities, though there isn't necessarily any reason why
>> we couldn't.  But I'm curious as to why you haven't submitted the tool
>> itself?
>
> That's a great question! I kept it external for a few reasons:
>
> First, I'm still pretty new to kernel development and wanted the freedom
> to iterate quickly as I learn what checks are actually useful. Being 
> external means I can push updates immediately when someone points out
> a new common mistake (like Greg just did with the date check!).

I would guess, though, that you would get more people pointing things
out if you were to post the tool to the list and eventually get it in.
The kernel cycle isn't *that* slow in the end...

> Second, I wrote everything in bash for simplicity, which probably isn't
> the best fit for the kernel's scripts/ directory. Plus, as Greg mentioned
> in his reply, many of these checks really belong in checkpatch.pl rather
> than a separate tool.

It wouldn't be the only bash script, certainly.

> So my plan now is to work on patches for checkpatch.pl to add the most
> useful checks there (where they belong), while keeping the workflow 
> helpers as an external toolkit.

It's your tool, you should develop it as you see fit, but keeping it
separate will make it harder to attract people to try it out.

Sending improvements to checkpatch is, of course, a good thing to do.

> Given this direction, would you prefer I withdraw this documentation 
> patch? I'm happy either way - just thought it might help other newcomers
> in the meantime, but I totally understand if you'd rather wait until
> the checks are properly integrated into checkpatch.pl.

For now, it's probably best to keep the documentation with the tool
itself; at least, that's how it seems to me.

Thanks,

jon