Date: Tue, 23 Apr 2024 15:04:55 -0500
From: Nathan Bossart <nathandbossart@gmail.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-hackers@postgresql.org
Subject: Re: Why does pgindent's README say to download typedefs.list from
 the buildfarm?
Message-ID: <20240423200455.GA850264@nathanxps13>
References: <20240422192218.GB367217@nathanxps13>
 <3154983.1713816488@sss.pgh.pa.us>
 <20240422202010.GA420168@nathanxps13>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="y0ulUmNC+osPPQO6"
Content-Disposition: inline
In-Reply-To: <20240422202010.GA420168@nathanxps13>
Archived-At: 
 <https://www.postgresql.org/message-id/20240423200455.GA850264%40nathanxps13>
Precedence: bulk


--y0ulUmNC+osPPQO6
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

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

--y0ulUmNC+osPPQO6
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="pgindent_readme_v1.patch"

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.
 

--y0ulUmNC+osPPQO6--