On Thu, Jan 22, 2026 at 5:33 PM Chao Li <[email protected]> wrote:
> > > > On Jan 8, 2026, at 09:38, Chao Li <[email protected]> wrote: > > > > > > > >> On Jan 8, 2026, at 07:13, Robert Treat <[email protected]> wrote: > >> > >> On Sat, Jan 3, 2026 at 11:30 PM Chao Li <[email protected]> wrote: > >>> On Jan 2, 2026, at 10:54, Robert Treat <[email protected]> wrote: > >>> Hi Robert, > >>> > >>> Thanks you very much for your review. > >>> > >>> > >>> On Thu, Dec 18, 2025 at 2:22 AM Chao Li <[email protected]> > wrote: > >>> Hi Hacker, > >> <snip> > >>> 2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” > missed “[]" with “COLUMN”, which is misleading, because “COLUMN” is > actually optional. > >>> > >>> 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. > >>> > >>> Thanks for confirming. > >>> > >>> > >>> 3. For all “alter column” sub-commands, "ALTER [ COLUMN ]” are > omitted, which is also confusing, because none of other sub-commands omit > their prefix part. > >>> > >>> > >>> 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. > >>> > >>> > >>> 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. > >>> > >>> That said, I understand your concern. The change did make the text > longer and added noise. In v2, I’ve 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. > >>> > >>> So, v2’s scope is significantly reduced, only a fix for my original > point 2 is retained. > >>> > >> > >> Makes sense to me and seems like an improvement, so +1. > >> > > > > Hi Robert, > > > > 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. > > > > Best regards, > > -- > > Chao Li (Evan) > > HighGo Software Co., Ltd. > > https://www.highgo.com/ > > Bump. This is a tiny doc fix. > PFA v3: Rebased, and added reviewer and discussion information. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
v3-0001-docs-reflect-optional-COLUMN-keyword-in-ALTER-TAB.patch
Description: Binary data
