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.
This commit is contained in:
Tom Lane
parent
a8f87d5d21
commit
3c03ee1a39
|
|
@ -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:
|
||||
|
||||
DOING THE INDENT RUN BEFORE A NORMAL COMMIT:
|
||||
|
||||
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
|
||||
|
||||
(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.)
|
||||
|
||||
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:
|
||||
|
||||
When you're done, "git commit" everything including the typedefs.list file
|
||||
you used.
|
||||
1) Download the latest typedef file from the buildfarm:
|
||||
|
||||
4) Add the newly created commits to the .git-blame-ignore-revs file so
|
||||
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 ../../..
|
||||
|
||||
5) When you're done, "git commit" everything including the typedefs.list file
|
||||
you used.
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue