[dpdk-dev] [PATCH v3 3/3] doc/guides: updated script usage for checking patches

Thomas Monjalon thomas at monjalon.net
Wed Jun 17 11:46:47 CEST 2020


02/06/2020 15:53, Ciara Power:
> The contributor's guide includes the usage of both the checkpatches and
> check-git-log scripts, which needed to be updated to reflect the now
> standardised format.

I think the doc update should be merged in the first patch.
In general, doc and code updates should come together.

[...]
>  The script usage is::
>  
> -   checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]"
> +   checkpatches.sh [-h] [-q] [-v] [-nX|-r range|patch1 [patch2] ...]"
>  
>  Where:
>  
>  * ``-h``: help, usage.
>  * ``-q``: quiet. Don't output anything for files without issues.
>  * ``-v``: verbose.
> +* ``-nX``: the number of commits to check.
> +* ``-r range``: the range to check, range must be a ``git log`` option.
>  * ``patchX``: path to one or more patches.

This is repeating what we get with the -h option.
I would suggest dropping the options explanation from this guide.

>  
>  Then the git logs should be checked using the ``check-git-log.sh`` script.
>  
>  The script usage is::
>  
> -   check-git-log.sh [range]
> +   check-git-log.sh [-h] [-nX|-r range]
>  
> -Where the range is a ``git log`` option.
> +Where:
> +
> +* ``-h``: help, usage.
> +* ``-nX``: the number of commits to check.
> +* ``-r range``: the range to check, range must be a ``git log`` option.

Same here, it is repeating what is documented with using -h.

If we really want to give an indication, we can say once for both that
the -n option is a number of commits from HEAD,
and -r option is a "git log" range.
A single sentence is probably enough.

In general, if we want guides to be read, they must be short.
John, as the doc owner, do you agree?




More information about the dev mailing list