Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20220910083835.2219239-1-niklas.soderlund@corigine.com>
In-Reply-To: <20220910083835.2219239-1-niklas.soderlund@corigine.com>
From:   Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date:   Tue, 13 Sep 2022 08:58:10 +0200
Message-ID: <CAKXUXMxbd9C832uq955tf1GoXO9+ckvpV84MB5=veQFzywen9Q@mail.gmail.com>
Subject: Re: [PATCH v6] checkpatch: warn for non-standard fixes tag style
To:     =?UTF-8?Q?Niklas_S=C3=B6derlund?= <niklas.soderlund@corigine.com>
Cc:     Dwaipayan Ray <dwaipayanray1@gmail.com>,
        Joe Perches <joe@perches.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Andy Whitcroft <apw@canonical.com>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        Philippe Schenker <philippe.schenker@toradex.com>,
        Stephen Rothwell <sfr@canb.auug.org.au>,
        oss-drivers@corigine.com, Simon Horman <simon.horman@corigine.com>,
        Louis Peens <louis.peens@corigine.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

On Sat, Sep 10, 2022 at 10:38 AM Niklas S=C3=B6derlund
<niklas.soderlund@corigine.com> wrote:
>
> Add a warning for fixes tags that does not fall in line with the
> standards specified by the community.
>
> Signed-off-by: Niklas S=C3=B6derlund <niklas.soderlund@corigine.com>
> Reviewed-by: Simon Horman <simon.horman@corigine.com>
> Reviewed-by: Louis Peens <louis.peens@corigine.com>
> ---
> * Changes since v5
> - Add support for --fix option for checkpatch.pl.
>
> * Changes since v4
> - Extend test to cover lines with whitespace before the fixes: tag, e.g.
>   match check on /^\s*fixes:?/i.
>
> * Changes since v3
> - Add test that title in tag match title of commit referenced by sha1.
>
> * Changes since v2
> - Change the pattern to match on 'fixes:?' to catch more malformed
>   tags.
>
> * Changes since v1
> - Update the documentation wording and add mention one cause of the
>   message can be that email program splits the tag over multiple lines.
> ---
>  Documentation/dev-tools/checkpatch.rst |  8 +++++
>  scripts/checkpatch.pl                  | 43 ++++++++++++++++++++++++++
>  2 files changed, 51 insertions(+)
>
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-t=
ools/checkpatch.rst
> index b52452bc2963..8c8456a3bd18 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst
> @@ -612,6 +612,14 @@ Commit message
>
>      See: https://www.kernel.org/doc/html/latest/process/submitting-patch=
es.html#describe-your-changes
>
> +  **BAD_FIXES_TAG**
> +    The Fixes: tag is malformed or does not fall in line with the standa=
rds
> +    specified by the community. This can occur if the tag have been spli=
t into
> +    multiple lines (e.g., when pasted in email program with word wrappin=
g
> +    enabled).
> +
> +    See: https://www.kernel.org/doc/html/latest/process/submitting-patch=
es.html#describe-your-changes
> +

Thanks for all the work on checkpatch here!

Just three nits:

does not fall in line with ~~> how about "is not aligned with" or
"does not follow"?

"specified" and "standards" is a "big" word. Let us be more brief and
avoid "specification" and "standard".

"standards specified by the community" ~> "community standards", maybe
even "community conventions"?

"when pasted in email program" ~> "when pasted in an email program"

Maybe you also add a sentence on word wrapping of Fixes: tags, such as:

Note that the Fixes: tag line shall not be wrapped.

Nevertheless, for the documentation part:
Reviewed-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Acked-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>

Lukas

>
>  Comparison style
>  ----------------
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index 79e759aac543..77f577535fc3 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -3140,6 +3140,49 @@ sub process {
>                         }
>                 }
>
> +# Check Fixes: styles is correct
> +               if (!$in_header_lines && $line =3D~ /^\s*fixes:?/i) {
> +                       my $orig_commit =3D "";
> +                       my $id =3D "0123456789ab";
> +                       my $title =3D "commit title";
> +                       my $tag_case =3D 1;
> +                       my $tag_space =3D 1;
> +                       my $id_length =3D 1;
> +                       my $id_case =3D 1;
> +                       my $title_has_quotes =3D 0;
> +
> +                       if ($line =3D~ /(\s*fixes:?)\s+([0-9a-f]{5,})\s+(=
$balanced_parens)/i) {
> +                               my $tag =3D $1;
> +                               $orig_commit =3D $2;
> +                               $title =3D $3;
> +
> +                               $tag_case =3D 0 if $tag eq "Fixes:";
> +                               $tag_space =3D 0 if ($line =3D~ /^fixes:?=
 [0-9a-f]{5,} ($balanced_parens)/i);
> +
> +                               $id_length =3D 0 if ($orig_commit =3D~ /^=
[0-9a-f]{12}$/i);
> +                               $id_case =3D 0 if ($orig_commit !~ /[A-F]=
/);
> +
> +                               # Always strip leading/trailing parens th=
en double quotes if existing
> +                               $title =3D substr($title, 1, -1);
> +                               if ($title =3D~ /^".*"$/) {
> +                                       $title =3D substr($title, 1, -1);
> +                                       $title_has_quotes =3D 1;
> +                               }
> +                       }
> +
> +                       my ($cid, $ctitle) =3D git_commit_info($orig_comm=
it, $id,
> +                                                            $title);
> +
> +                       if ($ctitle ne $title || $tag_case || $tag_space =
||
> +                           $id_length || $id_case || !$title_has_quotes)=
 {
> +                               if (WARN("BAD_FIXES_TAG",
> +                                    "Please use correct Fixes: style 'Fi=
xes: <12 chars of sha1> (\"<title line>\")' - ie: 'Fixes: $cid (\"$ctitle\"=
)'\n" . $herecurr) &&
> +                                   $fix) {
> +                                       $fixed[$fixlinenr] =3D "Fixes: $c=
id (\"$ctitle\")";
> +                               }
> +                       }
> +               }
> +
>  # Check email subject for common tools that don't need to be mentioned
>                 if ($in_header_lines &&
>                     $line =3D~ /^Subject:.*\b(?:checkpatch|sparse|smatch)=
\b[^:]/i) {
> --
> 2.37.3
>