On Mon, Apr 22, 2024 at 03:20:10PM -0500, Nathan Bossart wrote: > On Mon, Apr 22, 2024 at 04:08:08PM -0400, Tom Lane wrote: >> The problem with the README is that it describes that process, >> rather than the now-typical workflow of incrementally keeping >> the tree indented. I don't think we want to remove the info >> about how to do the full-monty process, but you're right that >> the README needs to explain the incremental method as being >> the one most developers would usually use. >> >> Want to write some text? > > Yup, I'll put something together.
Here is a first attempt. I'm not tremendously happy with it, but it at least gets something on the page to build on. I was originally going to copy/paste the relevant steps into the description of the incremental process, but that seemed kind-of silly, so I instead just pointed to the relevant steps of the "full" process, along with the deviations from those steps. That's a little more work for the reader, but maybe it isn't too bad... I plan to iterate on this patch some more. -- Nathan Bossart Amazon Web Services: https://aws.amazon.com
diff --git a/src/tools/pgindent/README b/src/tools/pgindent/README index b649a21f59..221e3fc010 100644 --- a/src/tools/pgindent/README +++ b/src/tools/pgindent/README @@ -1,8 +1,11 @@ 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. +The following process is used to maintain uniform layout style in our C and Perl +code. Once in each development cycle, a complete, independent run is performed. +Additionally, an abridged run should be performed on every new commit to +minimize deviations from pgindent's preferred style. See below for more details +on each type of run. You might find this blog post interesting: http://adpgtech.blogspot.com/2015/05/running-pgindent-on-non-core-code-or.html @@ -25,7 +28,20 @@ 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 AN INCREMENTAL, PER-COMMIT INDENT RUN: + +First, complete steps 1-3 of a complete run listed below. Note that there is +no need to download the typedef file from the buildfarm. Standard practice is +to manually update this file as needed in the same commit that adds or removes +types. The once-per-development-cycle run will resolve any differences between +the incrementally updated version of the file and a clean, autogenerated one. + +Finally, complete steps 1-3 of the validation section below. Ensure that any +changes made by pgindent are included in the patch prior to committing. If you +forget to do so, add the missed pgindent changes in a follow-up commit and also +do step 4 of the validation section below. + +DOING A COMPLETE, ONCE-PER-DEVELOPMENT-CYCLE INDENT RUN: 1) Change directory to the top of the source tree.