Content-Type: text/plain;
	charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.300.41.1.7\))
Subject: Re: DOC: fixes multiple errors in alter table doc
From: Chao Li <li.evan.chao@gmail.com>
In-Reply-To: <E9FEE306-E00D-4ECA-97B0-219BE7AB5169@gmail.com>
Date: Thu, 22 Jan 2026 17:32:38 +0800
Cc: Postgres hackers <pgsql-hackers@lists.postgresql.org>
Content-Transfer-Encoding: quoted-printable
Message-Id: <7D4CB5FF-6599-4157-A9E3-7B5E2CB96CEE@gmail.com>
References: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com>
 <CABV9wwMPmo-dg=oV+NaJGa_==uo5+TTvk58aNtjVQZBtMcRVBw@mail.gmail.com>
 <CAEoWx2kkh5kCZwYOYaOVShjh3un2mJTGrcFZyhJXd320PHYfJw@mail.gmail.com>
 <CAJSLCQ10_gia2-GzQndwoM-n-v2DWz4LnAY5jyO2ZmNiE+56tA@mail.gmail.com>
 <E9FEE306-E00D-4ECA-97B0-219BE7AB5169@gmail.com>
To: Robert Treat <rob@xzilla.net>
Archived-At: <https://www.postgresql.org/message-id/7D4CB5FF-6599-4157-A9E3-7B5E2CB96CEE%40gmail.com>
Precedence: bulk


> On Jan 8, 2026, at 09:38, Chao Li <li.evan.chao@gmail.com> wrote:
>=20
>=20
>=20
>> On Jan 8, 2026, at 07:13, Robert Treat <rob@xzilla.net> wrote:
>>=20
>> On Sat, Jan 3, 2026 at 11:30=E2=80=AFPM Chao Li =
<li.evan.chao@gmail.com> wrote:
>>> On Jan 2, 2026, at 10:54, Robert Treat <rob@xzilla.net> wrote:
>>> Hi Robert,
>>>=20
>>> Thanks you very much for your review.
>>>=20
>>>=20
>>> On Thu, Dec 18, 2025 at 2:22=E2=80=AFAM Chao Li =
<li.evan.chao@gmail.com> wrote:
>>> Hi Hacker,
>> <snip>
>>> 2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]=E2=80=
=9D missed =E2=80=9C[]" with =E2=80=9CCOLUMN=E2=80=9D, which is =
misleading, because =E2=80=9CCOLUMN=E2=80=9D is actually optional.
>>>=20
>>> Seems technically correct and potentially useful, and I see you
>>> handled this for the DROP COLUMN variant as well, so I could see a =
+1
>>> on this one.
>>>=20
>>> Thanks for confirming.
>>>=20
>>>=20
>>> 3. For all =E2=80=9Calter column=E2=80=9D sub-commands, "ALTER [ =
COLUMN ]=E2=80=9D are omitted, which is also confusing, because none of =
other sub-commands omit their prefix part.
>>>=20
>>>=20
>>> Hmm... I'm curious what you find confusing about this. Is the
>>> confusion in trying to find or understand the information presented,
>>> or confusing as to why it isn't all documented the same way? The
>>> downside of your "fix" is that this introduces a lot of extra text
>>> that is more or less noise, especially for folks trying to skim the
>>> documents looking for very specific command references.  And while I
>>> agree that we aren't 100% consistent on this within the ALTER TABLE
>>> subcommands, we use this same mixed pattern of omission on other =
pages
>>> (see ALTER TYPE for instance). If we were to insist on making this
>>> consistent here, I think we'd probably need to look at other pages =
as
>>> well and evaluate or update them too. I'm not sure that would be an
>>> improvement though.
>>>=20
>>>=20
>>> The confusion came from my own first-time reading of the =
documentation. Since the page is quite long, when I was reading the =
action descriptions and wanted to confirm the exact sub-command syntax, =
I often had to scroll back up to the syntax section. That led me to =
think it might be helpful to include the full sub-command form directly =
with the action descriptions.
>>>=20
>>> That said, I understand your concern. The change did make the text =
longer and added noise. In v2, I=E2=80=99ve therefore reverted that =
broader change. As you pointed out, if we were to pursue this kind of =
consistency, it would need to be handled across other similar pages as =
well, which would be better done as a dedicated and more carefully =
scoped patch.
>>>=20
>>> So, v2=E2=80=99s scope is significantly reduced, only a fix for my =
original point 2 is retained.
>>>=20
>>=20
>> Makes sense to me and seems like an improvement, so +1.
>>=20
>=20
> Hi Robert,
>=20
> Thank you very much for your review. This is the CF entry =
https://commitfest.postgresql.org/patch/6328/, you may add you as a =
reviewer. And I just changed the status to Ready for Committer.
>=20
> Best regards,
> --
> Chao Li (Evan)
> HighGo Software Co., Ltd.
> https://www.highgo.com/

Bump. This is a tiny doc fix.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/