[PATCH v3 3/4] patman: Add new tags for finer-grained changelog control

[Simon Glass]

HI Sean,

On Sun, 3 May 2020 at 15:55, Sean Anderson <seanga2 at gmail.com> wrote:
>
> By default patman generates a combined changelog for the cover letter. This
> may not always be desireable.

desirable

>
> Many patches may have the same changes. These can be coalesced with
> "Series-process-log: uniq", but this is imperfect. Similar changes like
> "Move foo to patch 7" will not be merged with the similar "Move foo to this
> patch from patch 6".
>
> Changes may not make sense outside of the patch they are written for. For
> example, a change line of "Add check for bar" does not make sense outside
> of the context in which bar might be checked for. Some changes like "New"
> or "Lint" may be repeated many times throughout different change logs, but
> carry no useful information in a summary.
>
> Lastly, I like to summarize the broad strokes of the changes I have made in
> the cover letter, while documenting all the details in the appropriate
> patches. I think this make it easier to get a good feel for what has

makes

> changed, without making it difficult to wade through every change in the
> whole series.
>
> This patch adds two new tags to add changelog entries which only appear in
> the cover letter, or only appear in the commit. Changes documented with
> "Commit-changes" will only appear in the commit, and will not appear in the
> cover letter. Changes documented with "Cover-changes" will not appear in
> any commit, and will only appear in the cover letter.
>
> Signed-off-by: Sean Anderson <seanga2 at gmail.com>
> ---
>
> (no changes since v2)
>
> Changes in v2:
> - Add documentation for new tags
> - Switch to using commit tags for changelog control, instead of
>   command-line options
>
>  tools/patman/README         | 17 +++++++++
>  tools/patman/patchstream.py | 73 ++++++++++++++++++++++---------------
>  tools/patman/patman.py      |  2 +-
>  tools/patman/series.py      | 13 ++++++-
>  4 files changed, 73 insertions(+), 32 deletions(-)

Reviewed-by: Simon Glass <sjg at chromium.org>

(with fixes added)

Also please can you rebase on mainline as there is a minor conflict in series.py

>
> diff --git a/tools/patman/README b/tools/patman/README
> index d1d9891c4c..5a67a49e88 100644
> --- a/tools/patman/README
> +++ b/tools/patman/README
> @@ -247,6 +247,23 @@ Series-changes: n
>         to update the log there and then, knowing that the script will
>         do the rest.
>
> +Commit-changes: n
> +- This line will not appear in the cover-letter changelog
> +<blank line>
> +       This tag is like Series-changes, except changes in this changelog will
> +       only appear in the changelog of the commit this tag is in. This is
> +       useful when you want to add notes which may not make sense in the cover
> +       letter. For example, you can have short changes such as "New" or
> +       "Lint".
> +
> +Cover-changes: n
> +- This line will only appear in the cover letter
> +<blank line>
> +       This tag is like Series-changes, except changes in this changelog will
> +       only appear in the cover-letter changelog. This is useful to summarize
> +       changes made with Commit-changes, or to add additional context to
> +       changes.
> +
>  Patch-cc: Their Name <email>
>         This copies a single patch to another email address. Note that the
>         Cc: used by git send-email is ignored by patman, but will be
> diff --git a/tools/patman/patchstream.py b/tools/patman/patchstream.py
> index df3eb7483b..f29ad87e70 100644
> --- a/tools/patman/patchstream.py
> +++ b/tools/patman/patchstream.py
> @@ -24,11 +24,8 @@ re_allowed_after_test = re.compile('^Signed-off-by:')
>  # Signoffs
>  re_signoff = re.compile('^Signed-off-by: *(.*)')
>
> -# The start of the cover letter
> -re_cover = re.compile('^Cover-letter:')
> -
> -# A cover letter Cc
> -re_cover_cc = re.compile('^Cover-letter-cc: *(.*)')
> +# Cover letter tag
> +re_cover = re.compile('^Cover-([a-z-]*): *(.*)')
>
>  # Patch series tag
>  re_series_tag = re.compile('^Series-([a-z-]*): *(.*)')
> @@ -65,7 +62,7 @@ class PatchStream:
>      def __init__(self, series, name=None, is_log=False):
>          self.skip_blank = False          # True to skip a single blank line
>          self.found_test = False          # Found a TEST= line
> -        self.lines_after_test = 0        # MNumber of lines found after TEST=
> +        self.lines_after_test = 0        # Number of lines found after TEST=
>          self.warn = []                   # List of warnings we have collected
>          self.linenum = 1                 # Output line number we are up to
>          self.in_section = None           # Name of start...END section we are in
> @@ -73,7 +70,8 @@ class PatchStream:
>          self.section = []                # The current section...END section
>          self.series = series             # Info about the patch series
>          self.is_log = is_log             # True if indent like git log
> -        self.in_change = 0               # Non-zero if we are in a change list
> +        self.in_change = None            # Name of the change list we are in
> +        self.change_version = 0          # Non-zero if we are in a change list
>          self.blank_count = 0             # Number of blank lines stored up
>          self.state = STATE_MSG_HEADER    # What state are we in?
>          self.signoff = []                # Contents of signoff line
> @@ -124,6 +122,14 @@ class PatchStream:
>              self.skip_blank = True
>              self.section = []
>
> +    def ParseVersion(self, value, line):
> +        """Parse a version from a *-changes tag"""

Args:

Returns:

> +        try:
> +            return int(value)
> +        except ValueError as str:
> +            raise ValueError("%s: Cannot decode version info '%s'" %
> +                (self.commit.hash, line))
> +

[..]

Regards,
Simon