Doc: update src/tools/pgindent/README for current practice.

This README explains how to run pgindent, but it was written
for our former practice of running pgindent only infrequently.
Nowadays the plan is to keep the tree indent-clean all the time,
so the typical thing is to do an incremental pgindent run with
each commit.  Revise to explain that as the normal case, and
the infrequent full-on process as a separate thing.

For now, pgperltidy is still a run-it-infrequently item.

diff --git a/src/tools/pgindent/README b/src/tools/pgindent/README
index b649a21f59302c108a530dd627c3f5fac8d756f0..b6cd4c6f6b768f8b4f3ec705d370abae934d68fa 100644 (file)
--- a/src/tools/pgindent/README
+++ b/src/tools/pgindent/README
@@ -1,8 +1,9 @@
 pgindent'ing the PostgreSQL source tree
 =======================================
 
-We run this process at least once in each development cycle,
-to maintain uniform layout style in our C and Perl code.
+pgindent is used to maintain uniform layout style in our C and Perl code,
+and should be run for every commit. There are additional code beautification
+tasks which should be performed at least once per release cycle.
 
 You might find this blog post interesting:
 http://adpgtech.blogspot.com/2015/05/running-pgindent-on-non-core-code-or.html
@@ -25,45 +26,31 @@ PREREQUISITES:
    Or if you have cpanm installed, you can just use:
    cpanm https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/Perl-Tidy-20230309.tar.gz
 
-DOING THE INDENT RUN:
 
-1) Change directory to the top of the source tree.
-
-2) Download the latest typedef file from the buildfarm:
+DOING THE INDENT RUN BEFORE A NORMAL COMMIT:
 
-   wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl
-
-   (See https://buildfarm.postgresql.org/cgi-bin/typedefs.pl?show_list for a full
-   list of typedef files, if you want to indent some back branch.)
+1) Change directory to the top of the source tree.
 
-3) Run pgindent on the C files:
+2) Run pgindent on the C files:
 
    src/tools/pgindent/pgindent .
 
    If any files generate errors, restore their original versions with
    "git checkout", and see below for cleanup ideas.
 
-4) Indent the Perl code using perltidy:
-
-   src/tools/pgindent/pgperltidy .
-
-   If you want to use some perltidy version that's not in your PATH,
-   first set the PERLTIDY environment variable to point to it.
-
-5) Reformat the bootstrap catalog data files:
-
-   ./configure     # "make" will not work in an unconfigured tree
-   cd src/include/catalog
-   make reformat-dat-files
-   cd ../../..
-
-VALIDATION:
-
-1) Check for any newly-created files using "git status"; there shouldn't
+3) Check for any newly-created files using "git status"; there shouldn't
    be any.  (pgindent leaves *.BAK files behind if it has trouble, while
    perltidy leaves *.LOG files behind.)
 
-2) Do a full test build:
+4) If pgindent wants to change anything your commit wasn't touching,
+   stop and figure out why.  If it is making ugly whitespace changes
+   around typedefs your commit adds, you need to add those typedefs
+   to src/tools/pgindent/typedefs.list.
+
+5) If you have the patience, it's worth eyeballing the "git diff" output
+   for any egregiously ugly changes.  See below for cleanup ideas.
+
+6) Do a full test build:
 
    make -s clean
    make -s all # look for unexpected warnings, and errors of course
@@ -75,14 +62,38 @@ VALIDATION:
    header files that get copied into ecpg output; if so, adjust the
    expected-files to match.
 
-3) If you have the patience, it's worth eyeballing the "git diff" output
-   for any egregiously ugly changes.  See below for cleanup ideas.
 
+AT LEAST ONCE PER RELEASE CYCLE:
+
+1) Download the latest typedef file from the buildfarm:
+
+   wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl
+
+   This step resolves any differences between the incrementally updated
+   version of the file and a clean, autogenerated one.
+   (See https://buildfarm.postgresql.org/cgi-bin/typedefs.pl?show_list for
+   a full list of typedef files, if you want to indent some back branch.)
+
+2) Run pgindent as above.
+
+3) Indent the Perl code using perltidy:
+
+   src/tools/pgindent/pgperltidy .
+
+   If you want to use some perltidy version that's not in your PATH,
+   first set the PERLTIDY environment variable to point to it.
+
+4) Reformat the bootstrap catalog data files:
+
+   ./configure     # "make" will not work in an unconfigured tree
+   cd src/include/catalog
+   make reformat-dat-files
+   cd ../../..
 
-When you're done, "git commit" everything including the typedefs.list file
-you used.
+5) When you're done, "git commit" everything including the typedefs.list file
+   you used.
 
-4) Add the newly created commits to the .git-blame-ignore-revs file so
+6) Add the newly created commit(s) to the .git-blame-ignore-revs file so
    that "git blame" ignores the commits (for anybody that has opted-in
    to using the ignore file).  Follow the instructions that appear at
    the top of the .git-blame-ignore-revs file.