scripts: add Perl script to add links to release notes

Reported-by: jian he
Discussion: https://postgr.es/m/ZuYsS5XdA7hVcV9l@momjian.us

Backpatch-through: 12

diff --git a/src/tools/RELEASE_CHANGES b/src/tools/RELEASE_CHANGES
index 5cf2a4dda3c4bc7f8c0fefd52cb39645d28497f5..2d0fb296f950c2edfd568171344e2d0d6b4d14c4 100644 (file)
--- a/src/tools/RELEASE_CHANGES
+++ b/src/tools/RELEASE_CHANGES
@@ -10,6 +10,7 @@ For All Releases (major, minor, beta, RC)
        o update doc/src/sgml/release-NN.sgml in relevant branches
        o run spellchecker on result
        o add SGML markup
+       o run src/tools/add_commit_links.pl
 
 * Update timezone data to match latest IANA timezone database and new
   Windows releases, if any (see src/timezone/README)

diff --git a/src/tools/add_commit_links.pl b/src/tools/add_commit_links.pl
new file mode 100755 (executable)
index 0000000..ebfc97e
--- /dev/null
+++ b/src/tools/add_commit_links.pl
@@ -0,0 +1,136 @@
+#! /usr/bin/perl
+
+#################################################################
+# add_commit_links.pl -- add commit links to the release notes
+#
+# Copyright (c) 2024, PostgreSQL Global Development Group
+#
+# src/tools/add_commit_links.pl
+#################################################################
+
+#
+# This script adds commit links to the release notes.
+#
+# Usage: cd to top of source tree and issue
+#      src/tools/add_commit_links.pl release_notes_file
+#
+# The script can add links for release note items that lack them, and update
+# those that have them.  The script is sensitive to the release note file being
+# in a specific format:
+#
+#  * File name contains the major version number preceded by a dash
+#    and followed by a period
+#  * Commit text is generated by src/tools/git_changelog
+#  * SGML comments around commit text start in the first column
+#  * The commit item title ends with an attribution that ends with
+#    a closing parentheses
+#  * previously added URL link text is unmodified
+#  * a "<para>" follows the commit item title
+#
+# The major version number is used to select the commit hash for minor
+# releases.  An error will be generated if valid commits are found but
+# no proper location for the commit links is found.
+
+use strict;
+use warnings FATAL => 'all';
+
+sub process_file
+{
+       my $file = shift;
+
+       my $in_comment = 0;
+       my $prev_line_ended_with_paren = 0;
+       my $prev_leading_space = '';
+       my $lineno = 0;
+
+       my @hashes = ();
+
+       my $tmpfile = $file . '.tmp';
+
+       # Get major version number from the file name.
+       $file =~ m/-(\d+)\./;
+       my $major_version = $1;
+
+       open(my $fh, '<', $file) || die "could not open file %s: $!\n", $file;
+       open(my $tfh, '>', $tmpfile) || die "could not open file %s: $!\n",
+         $tmpfile;
+
+       while (<$fh>)
+       {
+               $lineno++;
+
+               $in_comment = 1 if (m/^<!--/);
+
+               # skip over commit links because we will add them below
+               next
+                 if (!$in_comment &&
+                       m{^\s*<ulink url="&commit_baseurl;[\da-f]+">&sect;</ulink>\s*$});
+
+               if ($in_comment && m/\[([\da-f]+)\]/)
+               {
+                       my $hash = $1;
+
+                       # major release item
+                       (!m/^Branch:/) && push(@hashes, $hash);
+
+                       # minor release item
+                       m/^Branch:/ &&
+                         defined($major_version) &&
+                         m/_${major_version}_/ &&
+                         push(@hashes, $hash);
+               }
+
+               if (!$in_comment && m{</para>})
+               {
+                       if (@hashes)
+                       {
+                               if ($prev_line_ended_with_paren)
+                               {
+                                       for my $hash (@hashes)
+                                       {
+                                               print({$tfh}
+                                                         "$prev_leading_space<ulink url=\"&commit_baseurl;$hash\">&sect;</ulink>\n"
+                                               );
+                                       }
+                                       @hashes = ();
+                               }
+                               else
+                               {
+                                       printf(
+                                               "hashes found but no matching text found for placement on line %s\n",
+                                               $lineno);
+                                       exit(1);
+                               }
+                       }
+               }
+
+               print({$tfh} $_);
+
+               $prev_line_ended_with_paren = m/\)\s*$/;
+
+               m/^(\s*)/;
+               $prev_leading_space = $1;
+
+               $in_comment = 0 if (m/^-->/);
+       }
+
+       close($fh);
+       close($tfh);
+
+       rename($tmpfile, $file) || die "could not rename %s to %s: $!\n",
+         $tmpfile,
+         $file;
+
+       return;
+}
+
+if (@ARGV == 0)
+{
+       printf(STDERR "Usage: %s release_notes_file [...]\n", $0);
+       exit(1);
+}
+
+for my $file (@ARGV)
+{
+       process_file($file);
+}