Skip to contentSkip to conversation

patman: Add changelog customization options

PATCH Superseded Sean Anderson 2 participants 5 messages Apr 13, 2020 – Apr 19, 2020

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v2 cover patman: Add changelog customization options

This series adds a few changes I have been using locally as new behaviour for patman.

Changes in v2:
- Add a note when there are no changes in the current revision
- Add documentation for new tags
- Add patch for multi-line changes in changelogs
- Switch to using commit tags for changelog control, instead of command-line options

Sean Anderson (3):
patman: Add option to suppress empty changelog entries
patman: Add new tags for finer-grained changelog control
patman: Support multi-line changes in changelogs

 tools/patman/README         | 27 ++++++++++-
 tools/patman/patchstream.py | 96 +++++++++++++++++++++++++------------
 tools/patman/patman.py      |  2 +-
 tools/patman/series.py      | 49 ++++++++++++++-----
 4 files changed, 129 insertions(+), 45 deletions(-)
Signature · 1 line
2.25.1
#1 lore raw

PATCH v2 1/3 patman: Add option to suppress empty changelog entries

Patman outputs a line for every edition of the series in every patch, regardless of whether any changes were made. This can result in many redundant lines in patch changelogs, especially when a patch did not exist before a certain revision. For example, the existing behaviour could result in a changelog of

Changes in v7: None
Changes in v6: None
Changes in v5:
- Make a change

Changes in v4: None

Changes in v3:
- New

Changes in v2: None

With this patch applied and with --no-empty-changes, the same patch would look like

(no changes since v5)

Changes in v5:
- Make a change

Changes in v3:
- New

This is entirely aesthetic, but I think it reduces clutter, especially for patches added later on in a series.

---

Changes in v2:
- Add a note when there are no changes in the current revision
- Make this the default behaviour, and remove the option

 tools/patman/patchstream.py |  2 +-
 tools/patman/series.py      | 40 +++++++++++++++++++++++++++----------
 2 files changed, 30 insertions(+), 12 deletions(-)
tools/patman/patchstream.py +1 -1
index df3eb7483b..a83497d79f 100644
@@ -340,7 +340,7 @@ class PatchStream:
             elif line == '---':
                 self.state = STATE_DIFFS
 
-                # Output the tags (signeoff first), then change list
+                # Output the tags (signoff first), then change list
                 out = []
                 log = self.series.MakeChangeLog(self.commit)
                 out += [line]
tools/patman/series.py +29 -11
index a15f7625ed..ca42e5e966 100644
@@ -146,38 +146,56 @@ class Series(dict):
             Changes in v4:
             - Jog the dial back closer to the widget
 
-            Changes in v3: None
             Changes in v2:
             - Fix the widget
             - Jog the dial
 
-            etc.
+            If there are no new changes in a patch, a note will be added
+
+            (no changes since v2)
+
+            Changes in v2:
+            - Fix the widget
+            - Jog the dial
         """
+        versions = sorted(self.changes, reverse=True)
+        newest_version = 1
+        try:
+            newest_version = max(int(self.version), versions[0])
+        except (IndexError, ValueError):
+            pass
+
         final = []
         process_it = self.get('process_log', '').split(',')
         process_it = [item.strip() for item in process_it]
         need_blank = False
-        for change in sorted(self.changes, reverse=True):
+        for version in versions:
             out = []
-            for this_commit, text in self.changes[change]:
+            for this_commit, text in self.changes[version]:
                 if commit and this_commit != commit:
                     continue
                 if 'uniq' not in process_it or text not in out:
                     out.append(text)
-            line = 'Changes in v%d:' % change
-            have_changes = len(out) > 0
             if 'sort' in process_it:
                 out = sorted(out)
+            have_changes = len(out) > 0
+            line = 'Changes in v%d:' % version
             if have_changes:
                 out.insert(0, line)
-            else:
-                out = [line + ' None']
-            if need_blank:
-                out.insert(0, '')
+                if version < newest_version:
+                    out.insert(0, '')
+                    out.insert(0, '(no changes since v%d)' % version)
+                    newest_version = 0
+                # Only add a new line if we output something
+                if need_blank:
+                    out.insert(0, '')
             final += out
             need_blank = have_changes
-        if self.changes:
+
+        if len(final) > 0:
             final.append('')
+        else:
+            final = ['(no changes since v1)', '']
         return final
 
     def DoChecks(self):
Signature · 1 line
2.25.1
#2 lore raw

PATCH v2 1/3 patman: Add option to suppress empty changelog entries

Hi Sean,

Quoted 36 lines · Sean Anderson

Patman outputs a line for every edition of the series in every patch, regardless of whether any changes were made. This can result in many redundant lines in patch changelogs, especially when a patch did not exist before a certain revision. For example, the existing behaviour could result in a changelog of

Changes in v7: None
Changes in v6: None
Changes in v5:
- Make a change

Changes in v4: None

Changes in v3:
- New

Changes in v2: None

With this patch applied and with --no-empty-changes, the same patch would look like

(no changes since v5)

Changes in v5:
- Make a change

Changes in v3:
- New

This is entirely aesthetic, but I think it reduces clutter, especially for patches added later on in a series.

---

Quoted 8 lines

Changes in v2:
- Add a note when there are no changes in the current revision
- Make this the default behaviour, and remove the option

 tools/patman/patchstream.py |  2 +-
 tools/patman/series.py      | 40 +++++++++++++++++++++++++++----------
 2 files changed, 30 insertions(+), 12 deletions(-)

Thanks for sending this series. I think the way that you have it working is fine.

But a few problems:

1. patman --test fails
2. The new behaviour needs a few tests, or at least test changes
3. I think you should mention the suppression of change-log info in the README
4. For me I see strange output:

Changes in v5:
- This is my cover change

(no changes since v4)

Changes in v4:
- Add linux/err.h header
- Rename acpi-probed to linux,probed

5. Can you update your commit subjects to reflect what you are doing now?

Regards,
Simon

#3 lore raw

PATCH v2 2/3 patman: Add new tags for finer-grained changelog control

In reply to Sean Anderson

By default patman generates a combined changelog for the cover letter. This may not always be desireable.

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 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.

---

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 | 71 ++++++++++++++++++++++---------------
 tools/patman/patman.py      |  2 +-
 tools/patman/series.py      | 13 +++++--
 4 files changed, 72 insertions(+), 31 deletions(-)
tools/patman/README +17 -0
index 02d5829744..ce912aacbb 100644
@@ -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
tools/patman/patchstream.py +43 -28

141 lines not on this page · raw message

tools/patman/patman.py +1 -1
index cf53e532dd..6ee0597ff4 100755
@@ -61,7 +61,7 @@ parser.add_option('--no-check', action='store_false', dest='check_patch',
                   default=True,
                   help="Don't check for patch compliance")
 parser.add_option('--no-tags', action='store_false', dest='process_tags',
-                  default=True, help="Don't process subject tags as aliaes")
+                  default=True, help="Don't process subject tags as aliases")
 parser.add_option('--smtp-server', type='str',
                   help="Specify the SMTP server to 'git send-email'")
 parser.add_option('-T', '--thread', action='store_true', dest='thread',
tools/patman/series.py +11 -2
index ca42e5e966..4fa06344b5 100644
@@ -4,6 +4,7 @@
 
 from __future__ import print_function
 
+import collections
 import itertools
 import os
 
@@ -158,7 +159,15 @@ class Series(dict):
             - Fix the widget
             - Jog the dial
         """
-        versions = sorted(self.changes, reverse=True)
+        # Collect changes from the series and this commit
+        changes = collections.defaultdict(list)
+        for version, changelist in self.changes.items():
+            changes[version] += changelist
+        if commit:
+            for version, changelist in commit.changes.items():
+                changes[version] += [[commit, text] for text in changelist]
+
+        versions = sorted(changes, reverse=True)
         newest_version = 1
         try:
             newest_version = max(int(self.version), versions[0])
@@ -171,7 +180,7 @@ class Series(dict):
         need_blank = False
         for version in versions:
             out = []
-            for this_commit, text in self.changes[version]:
+            for this_commit, text in changes[version]:
                 if commit and this_commit != commit:
                     continue
                 if 'uniq' not in process_it or text not in out:
Signature · 1 line
2.25.1
#4 lore raw

PATCH v2 3/3 patman: Support multi-line changes in changelogs

In reply to Sean Anderson

This patch adds support to multi-line changes. That is, if one has a line in a changelog like
- Do a thing but
it spans multiple lines
Using Series-process-log sort would sort as if those lines were unrelated. With this patch, any change line starting with whitespace will be considered part of the change before it.

---

Changes in v2:
- New

 tools/patman/README         | 10 ++++++++--
 tools/patman/patchstream.py | 35 +++++++++++++++++++++++++++--------
 2 files changed, 35 insertions(+), 10 deletions(-)
tools/patman/README +8 -2
index ce912aacbb..433bbf1683 100644
@@ -270,8 +270,14 @@ Patch-cc: Their Name <email>
 	interpreted by git send-email if you use it.
 
 Series-process-log: sort, uniq
-	This tells patman to sort and/or uniq the change logs. It is
-	assumed that each change log entry is only a single line long.
+	This tells patman to sort and/or uniq the change logs. Changes may be
+	multiple lines long, as long as each subsequent line of a change begins
+	with a whitespace character. For example,
+
+- This change
+  continues onto the next line
+- But this change is separate
+
 	Use 'sort' to sort the entries, and 'uniq' to include only
 	unique entries. If omitted, no change log processing is done.
 	Separate each tag with a comma.
tools/patman/patchstream.py +27 -8
index f29ad87e70..eeac5d268e 100644
@@ -45,6 +45,9 @@ re_commit = re.compile('^commit ([0-9a-f]*)$')
 # We detect these since checkpatch doesn't always do it
 re_space_before_tab = re.compile('^[+].* \t')
 
+# Match indented lines for changes
+re_leading_whitespace = re.compile('^\s')
+
 # States we can be in - can we use range() and still have comments?
 STATE_MSG_HEADER = 0        # Still in the message header
 STATE_PATCH_SUBJECT = 1     # In patch subject (first line of log for a commit)
@@ -72,6 +75,7 @@ class PatchStream:
         self.is_log = is_log             # True if indent like git log
         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.change_lines = []           # Lines of the current change
         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
@@ -130,6 +134,20 @@ class PatchStream:
             raise ValueError("%s: Cannot decode version info '%s'" %
                 (self.commit.hash, line))
 
+    def FinalizeChange(self):
+        """Finalize a (multi-line) change and add it to the series or commit"""
+        if not self.change_lines:
+            return
+        change = '\n'.join(self.change_lines)
+
+        if self.in_change == 'Series':
+            self.series.AddChange(self.change_version, self.commit, change)
+        elif self.in_change == 'Cover':
+            self.series.AddChange(self.change_version, None, change)
+        elif self.in_change == 'Commit':
+            self.commit.AddChange(self.change_version, change)
+        self.change_lines = []
+
     def ProcessLine(self, line):
         """Process a single line of a patch file or commit log
 
@@ -170,6 +188,7 @@ class PatchStream:
         commit_tag_match = re_commit_tag.match(line)
         cover_match = re_cover.match(line)
         signoff_match = re_signoff.match(line)
+        leading_whitespace_match = re_leading_whitespace.match(line)
         tag_match = None
         if self.state == STATE_PATCH_HEADER:
             tag_match = re_tag.match(line)
@@ -210,6 +229,7 @@ class PatchStream:
             # is missing, fix it up.
             if self.in_change:
                 self.warn.append("Missing 'blank line' in section '%s-changes'" % self.in_change)
+                self.FinalizeChange()
                 self.in_change = None
                 self.change_version = 0
 
@@ -264,20 +284,18 @@ class PatchStream:
         elif self.in_change:
             if is_blank:
                 # Blank line ends this change list
+                self.FinalizeChange()
                 self.in_change = None
                 self.change_version = 0
             elif line == '---':
+                self.FinalizeChange()
                 self.in_change = None
                 self.change_version = 0
                 out = self.ProcessLine(line)
-            else:
-                if self.is_log:
-                    if self.in_change == 'Series':
-                        self.series.AddChange(self.change_version, self.commit, line)
-                    elif self.in_change == 'Cover':
-                        self.series.AddChange(self.change_version, None, line)
-                    elif self.in_change == 'Commit':
-                        self.commit.AddChange(self.change_version, line)
+            elif self.is_log:
+                if not leading_whitespace_match:
+                    self.FinalizeChange()
+                self.change_lines.append(line)
             self.skip_blank = False
 
         # Detect Series-xxx tags
@@ -370,6 +388,7 @@ class PatchStream:
 
     def Finalize(self):
         """Close out processing of this patch stream"""
+        self.FinalizeChange()
         self.CloseCommit()
         if self.lines_after_test:
             self.warn.append('Found %d lines after TEST=' %
Signature · 1 line
2.25.1