Merge pull request #6719 from EnterpriseDB/eatonphil-patch-1

Clarify a safe scenario for bdr.drop_node()

Author: djw-m

product_docs/docs/pgd/5.7/reference/functions-internal.mdx

@@ -161,16 +161,25 @@ bdr.difference_fix_xact_set_avoid_conflict()
 
 Drops a node's metadata.
 
+After a node has been `PARTED` its metadata remains present in the cluster's nodes. For example, the node will remain in the `bdr.node_sumary` results, marked as `PARTED`, until the node is dropped.
+
+Calling `bdr.drop_node('some node', force := true)` can be necessary
+and appropriate when a node becomes stuck while parting. Note that it
+skips past syncing any data out of the node being dropped, if there is
+any data on that node that still needs to be synced out. If a node
+stuck parting has already been reimaged or deleted, there is no harm
+in calling `bdr.drop_node` on it. Note that this must be called for
+this stuck node on all nodes in the cluster so they all have a
+consistent view that the node has been dropped.
+
 This function removes the metadata for a given node from the local
 database. The node can be either:
 
 -   The local node, in which case it removes all the node metadata, including information about remote nodes.
 -   A remote node, in which case it removes only metadata for that specific node.
 
-
-
 !!! Important When to use `bdr.drop_node()`
-Do not use `bdr.drop_node()` to drop node metadata and reuse node names. PGD can reuse existing node names providing the node name belongs to a node in a `PARTED` state. Use `bdr.part_node()` to remove the original node and place it in a `PARTED` state.
+It is not necessary to use `bdr.drop_node()` to drop node metadata just to reuse node names. PGD 5 and later can reuse existing node names as long as the node name in question belongs to a node in a `PARTED` state. Instead of dropping the node, use `bdr.part_node()` to remove the original node and place it in a `PARTED`.
 
 Use of this internal function is limited to: