Nathan Bossart <nathandboss...@gmail.com> writes:
> On Wed, May 15, 2024 at 04:07:18PM -0400, Robert Haas wrote:
>> How's this?
> I compared this with my v1, and the only bit of information there that I
> see missing in v3 is that validation step 4 only applies in the
> once-per-cycle run (or if you forget to pgindent before committing a
> patch). This might be why I was struggling to untangle the two types of
> pgindent runs in my attempt. Perhaps it's worth adding a note to that step
> about when it is required.
Oh ... another problem is that the VALIDATION steps really apply to
both kinds of indent runs, but it's not clear to me that that's
obvious in v3. Maybe the steps should be rearranged to be
(1) base case, (2) VALIDATION, (3) ONCE PER CYCLE.
At this point my OCD got the better of me and I did a little
additional wordsmithing. How about the attached?
regards, tom lane
diff --git a/src/tools/pgindent/README b/src/tools/pgindent/README
index b649a21f59..369f120eb0 100644
--- 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:
-
- wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl
+DOING THE INDENT RUN BEFORE A NORMAL COMMIT:
- (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.
