SOLR-18140: Try to bandaid the DELETENODE docs for a broken API

[epugh]

https://issues.apache.org/jira/browse/SOLR-18140

Description

A bandaid to make it clear that DELETENODE is how you remove a downed node from the cluster.

Solution

DELETENODE will delete all your replicas if your node is UP. But if your node is DOWN, then it removes it from ZK.

I added a TIP to call out that DELTENODE will delete the node from the cluster if it's down. But not if it's up.

The description of the API says it all on why this API isn't right: Delete all replicas off of the specified SolrCloud node.

It currently is POST /api/cluster/nodes/nodeName/clear {...} and it SHOULD be:

To delete replicas on a node
POST /api/cluster/nodes/nodeName/replicas/clear {...} or DELETE /api/cluster/nodes/nodeName/replicas {...}

And to delete the node:
POST /api/cluster/nodes/nodeName/clear {...} or DELETE /api/cluster/nodes/nodeName {...}

Tests

Please describe the tests you've developed or run to confirm this patch implements the feature or solves the problem.

Checklist

Please review the following and check all that apply:

• I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
• I have created a Jira issue and added the issue ID to my pull request title.
• I have given Solr maintainers access to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
• I have developed this patch against the main branch.
• I have run ./gradlew check.
• I have added tests for my changes.
• I have added documentation for the Reference Guide
• I have added a changelog entry for my change

[Copilot]

Pull request overview

Updates Solr Reference Guide documentation to better explain the behavior of the DELETENODE (v1) / cluster/nodes/{nodeName}/clear/ (v2) operation, especially in scenarios involving downed nodes.

Changes:

• Removes an extraneous Asciidoc continuation marker in the “Migrate Replicas” section.
• Adjusts DELETENODE wording about node “liveness” after replica deletion.
• Adds a TIP intended to clarify behavior when the target node is down.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new wording suggests DELETENODE can “remove the node from the cluster” when the node is down, and that it affects whether a node is a “live node”. In SolrCloud, liveness is determined by ZooKeeper /live_nodes and this API appears to just delete replicas assigned to the node (i.e., update cluster state); it doesn’t prevent the node from rejoining later if it comes back up. Consider rephrasing to explicitly say that when the node is down the command removes the node’s replica entries from cluster state/ZooKeeper (cleanup of references), rather than removing the node itself from the cluster or changing its liveness.

Suggested change

	If the node is currently down and you aren't bringing it back, then this command removes the node from the cluster.
	If the node is currently down and you aren't bringing it back, then this command removes that node's replica entries from the cluster state (ZooKeeper), cleaning up references to its replicas. It does not change the node's liveness in `/live_nodes`, and the node may still rejoin the cluster if it is started again later.