[PATCH] checkpatch: warn on unhandled placeholders in cover letters

[PATCH] checkpatch: warn on unhandled placeholders in cover letters

[Onur Özkan]

Adds a new check to detect unhandled placeholders in cover letters.
This prevents sending patch series with incomplete cover letters
containing auto generated subject or blurb lines such as:

    *** SUBJECT HERE ***
    *** BLURB HERE ***

These placeholders can be seen on mailing lists (e.g., searching
for "BLURB HERE" on lore.kernel.org). With this patch, checkpatch
will emit a warning when such text is found.

Example output on an invalid cover letter:

    WARNING: Incomplete cover letter: placeholder text detected
    #4: FILE: ./0000-cover-letter.patch:4:
    +Subject: [PATCH 0/4] *** SUBJECT HERE ***

    WARNING: Incomplete cover letter: placeholder text detected
    #9: FILE: ./0000-cover-letter.patch:9:
    +*** BLURB HERE ***

    total: 0 errors, 2 warnings, 24 lines checked

    NOTE: For some of the reported defects, checkpatch may be able to
	  mechanically convert to the typical style using --fix or --fix-inplace.

    ./0000-cover-letter.patch has style problems, please review.

    NOTE: If any of the errors are false positives, please report
	  them to the maintainer, see CHECKPATCH in MAINTAINERS.

Signed-off-by: Onur Özkan <work@onurozkan.dev>
---
 scripts/checkpatch.pl | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index e722dd6fa8ef..9d5ded376112 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3339,6 +3339,15 @@ sub process {
 				$fixed[$fixlinenr] =~ s/^/ /;
 			}
 		}
+# Check for unhandled placeholder text in cover letters
+		if ($filename =~ /cover-letter\.patch$/) {
+			if ($rawline =~ /^\+Subject:.*\*\*\* SUBJECT HERE \*\*\*/ ||
+				$rawline =~ /^\+\*\*\* BLURB HERE \*\*\*/) {
+				my $placeholder = $1 || $2;
+				WARN("COVER_LETTER_PLACEHOLDER",
+					 "Incomplete cover letter: placeholder text detected\n" . $herecurr);
+			}
+		}
 
 # Check for git id commit length and improperly formed commit descriptions
 # A correctly formed commit description is:
-- 
2.51.0

Re: [PATCH] checkpatch: warn on unhandled placeholders in cover letters

[Onur Özkan]

On Wed, 17 Sep 2025 14:49:09 +0300
Onur Özkan <work@onurozkan.dev> wrote:

> Adds a new check to detect unhandled placeholders in cover letters.
> This prevents sending patch series with incomplete cover letters
> containing auto generated subject or blurb lines such as:
> 
>     *** SUBJECT HERE ***
>     *** BLURB HERE ***
> 
> These placeholders can be seen on mailing lists (e.g., searching
> for "BLURB HERE" on lore.kernel.org). With this patch, checkpatch
> will emit a warning when such text is found.
> 
> Example output on an invalid cover letter:
> 
>     WARNING: Incomplete cover letter: placeholder text detected
>     #4: FILE: ./0000-cover-letter.patch:4:
>     +Subject: [PATCH 0/4] *** SUBJECT HERE ***
> 
>     WARNING: Incomplete cover letter: placeholder text detected
>     #9: FILE: ./0000-cover-letter.patch:9:
>     +*** BLURB HERE ***
> 
>     total: 0 errors, 2 warnings, 24 lines checked
> 
>     NOTE: For some of the reported defects, checkpatch may be able to
> 	  mechanically convert to the typical style using --fix or
> --fix-inplace.
> 
>     ./0000-cover-letter.patch has style problems, please review.
> 
>     NOTE: If any of the errors are false positives, please report
> 	  them to the maintainer, see CHECKPATCH in MAINTAINERS.
> 
> Signed-off-by: Onur Özkan <work@onurozkan.dev>
> ---
>  scripts/checkpatch.pl | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index e722dd6fa8ef..9d5ded376112 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -3339,6 +3339,15 @@ sub process {
>  				$fixed[$fixlinenr] =~ s/^/ /;
>  			}
>  		}
> +# Check for unhandled placeholder text in cover letters
> +		if ($filename =~ /cover-letter\.patch$/) {
> +			if ($rawline =~ /^\+Subject:.*\*\*\* SUBJECT
> HERE \*\*\*/ ||
> +				$rawline =~ /^\+\*\*\* BLURB HERE
> \*\*\*/) {
> +				my $placeholder = $1 || $2;
> +				WARN("COVER_LETTER_PLACEHOLDER",
> +					 "Incomplete cover letter:
> placeholder text detected\n" . $herecurr);
> +			}
> +		}
>  
>  # Check for git id commit length and improperly formed commit
> descriptions # A correctly formed commit description is:

I wasn't aware of the checkpatch documentation in
"Documentation/dev-tools/checkpatch.rst" file. I guess
COVER_LETTER_PLACEHOLDER needs to be documented there?

Regards,
Onur

Re: [PATCH] checkpatch: warn on unhandled placeholders in cover letters

[Joe Perches]

On Wed, 2025-09-17 at 17:01 +0300, Onur Özkan wrote:
> On Wed, 17 Sep 2025 14:49:09 +0300
> Onur Özkan <work@onurozkan.dev> wrote:
> 
> > Adds a new check to detect unhandled placeholders in cover letters.
> > This prevents sending patch series with incomplete cover letters
> > containing auto generated subject or blurb lines such as:
> > 
> >     *** SUBJECT HERE ***
> >     *** BLURB HERE ***
[]
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
[]
> > @@ -3339,6 +3339,15 @@ sub process {
> >  				$fixed[$fixlinenr] =~ s/^/ /;
> >  			}
> >  		}
> > +# Check for unhandled placeholder text in cover letters
> > +		if ($filename =~ /cover-letter\.patch$/) {

Probably don't need this $filename test but do need
some test and code like

		if (($in_commit_log || $in_header_lines) &&
		    $rawline =~ /(?:SUBJECT|BLURB) HERE/) {
			ERROR("PLACEHOLDER_USE",
			      "Placeholder text detected\n" . $herecurr);
		}

> > +			if ($rawline =~ /^\+Subject:.*\*\*\* SUBJECT
> > HERE \*\*\*/ ||
> > +				$rawline =~ /^\+\*\*\* BLURB HERE
> > \*\*\*/) {
> > +				my $placeholder = $1 || $2;

$placeholder isn't useful.

> > +				WARN("COVER_LETTER_PLACEHOLDER",

s/WARN/ERROR/

> > +					 "Incomplete cover letter:
> > placeholder text detected\n" . $herecurr);
> > +			}
> > +		}
[]
> I wasn't aware of the checkpatch documentation in
> "Documentation/dev-tools/checkpatch.rst" file. I guess
> COVER_LETTER_PLACEHOLDER needs to be documented there?

yes.

Re: [PATCH] checkpatch: warn on unhandled placeholders in cover letters

[Onur Özkan]

On Wed, 17 Sep 2025 08:43:16 -0700
Joe Perches <joe@perches.com> wrote:

> On Wed, 2025-09-17 at 17:01 +0300, Onur Özkan wrote:
> > On Wed, 17 Sep 2025 14:49:09 +0300
> > Onur Özkan <work@onurozkan.dev> wrote:
> > 
> > > Adds a new check to detect unhandled placeholders in cover
> > > letters. This prevents sending patch series with incomplete cover
> > > letters containing auto generated subject or blurb lines such as:
> > > 
> > >     *** SUBJECT HERE ***
> > >     *** BLURB HERE ***
> []
> > > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
> > > @@ -3339,6 +3339,15 @@ sub process {
> > >  				$fixed[$fixlinenr] =~ s/^/ /;
> > >  			}
> > >  		}
> > > +# Check for unhandled placeholder text in cover letters
> > > +		if ($filename =~ /cover-letter\.patch$/) {
> 
> Probably don't need this $filename test but do need
> some test and code like
> 
> 		if (($in_commit_log || $in_header_lines) &&
> 		    $rawline =~ /(?:SUBJECT|BLURB) HERE/) {
> 			ERROR("PLACEHOLDER_USE",
> 			      "Placeholder text detected\n" .
> $herecurr); }
> 
> > > +			if ($rawline =~ /^\+Subject:.*\*\*\*
> > > SUBJECT HERE \*\*\*/ ||
> > > +				$rawline =~ /^\+\*\*\* BLURB HERE
> > > \*\*\*/) {
> > > +				my $placeholder = $1 || $2;
> 
> $placeholder isn't useful.
> 

That was a left-over, sorry.

> > > +				WARN("COVER_LETTER_PLACEHOLDER",
> 
> s/WARN/ERROR/
> 
> > > +					 "Incomplete cover
> > > letter: placeholder text detected\n" . $herecurr);
> > > +			}
> > > +		}
> []
> > I wasn't aware of the checkpatch documentation in
> > "Documentation/dev-tools/checkpatch.rst" file. I guess
> > COVER_LETTER_PLACEHOLDER needs to be documented there?
> 
> yes.