diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 44ae7e0e87..188bafe4f9 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -154,6 +154,26 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
       This clause alters publication parameters originally set by
       <xref linkend="sql-createpublication"/>.  See there for more information.
      </para>
+     <caution>
+      <para>
+       When the partition root table is specified as the replication target
+       instead of its leaf tables, or this is either <literal>FOR ALL TABLES</literal>
+       or <literal>FOR TABLES IN SCHEMA</literal> publication, altering the
+       <literal>publish_via_partition_root</literal> parameter during
+       replication can cause data loss or duplication.
+       This happens because altering the parameter changes the identity and
+       schema of the publishing tables.
+       After running the <command>ALTER PUBLICATION ... SET</command> and
+       <link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>
+       command, the subscriber will subscribe to the appropriate table.
+      </para>
+      <para>
+       To prevent the issue, you can avoid modifying any leaf tables between
+       the <command>ALTER PUBLICATION ... SET</command> and
+       <command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command> and
+       refresh publication with <literal>copy_data = off</literal>.
+      </para>
+     </caution>
     </listitem>
    </varlistentry>