diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/tools/pgindent/README | 79 |
1 files changed, 45 insertions, 34 deletions
diff --git a/src/tools/pgindent/README b/src/tools/pgindent/README index b649a21f593..b6cd4c6f6b7 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: +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. |