Re: docs: clarify ALTER TABLE behavior on partitioned tables

On Fri, Jan 9, 2026 at 1:11 AM Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:

> >
> > The main points of interest:
> >
> > Saying that "ONLY" is a no-op when the observed behavior is that only
> the mentioned tables are affected seems wrong. I've removed those
> instances.
>
> Maybe the original phrasing “has no effect” wasn’t clear for what I meant.
> What I was trying to express is that ONLY is intended to control whether an
> action propagates to child tables: with ONLY it should not propagate, and
> without ONLY it should.
>
> For these particular sub-commands, however, the observed behavior is that
> they behave the same with or without ONLY. From a documentation
> perspective, stating that explicitly could help avoid user confusion.
>
> Separately, I do have a plan to tighten this behavior in the future: for
> these commands, specifying ONLY would raise an error instead. If such a
> change is merged later, the documentation note could naturally be removed
> at that point.
>
> So I’d like to keep the statement for now, but I’m very happy to adjust
> the wording if you have a clearer phrasing to suggest.
>

I've removed some I missed and tweaked others. I'm OK with leaving mention
of ONLY in these sections but what happens is that ONLY becomes implicitly
added to the command, which is what I'd rather communicate. The remaining
wording is a bit redundant now but flows nicely.

> Before I integrate your edits and prepare v3, I’d appreciate hearing your
> thoughts on the points about ONLY and “newly created”.
>
>
As I continue to think about the "newly created" material the more I
believe it is misplaced. That there is existing wording to that effect
doesn't change my conclusion. I would add no additional text here even if
you don't want to remove the existing mentions at this point. But I think
the scope of this patch should be increased to fix this misplacement as
well. Since moving content - refactoring - is what is happening here. In
the attached 0003 I've removed the paragraphs that this patch now makes
redundant within the alter table documentation. I wouldn't mind if they
got moved to somewhere in Chapter 5.12 (Table Partitioning) and not just
erased, along with ensuring that 5.12 includes how table creation
definition inheritance works and removing those mentions from the alter
table docs as well.

I'm not sure whether I'd fully remove all that content since some of it
does pertain just to table inheritance. That feature seems like something
best related to notes and not brought into the main flow like you are doing
with partitioned tables.

David J.