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.

[HoustonPutman]

This part isn't really necessary

If the node is currently down and you aren't bring it back

Because this part is applicable whether the node is down or up

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

I guess maybe the command is poorly named, but there is no idea of a persistent node in Solr, only something that has connected to the cluster and registered in live nodes...

[epugh]

Would you be willing to look at the text from your more knowlagable perspective? Do we cover in the Ref Guide this "no idea of a persistent node"? The part I struggle with is that the Nodes UI shows "down nodes"... Which makes you think they will come back. However, what makes a node "down" is that a replica for a collection just happens to be living on it.... I am struggling to convey that better...

Would adding to https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-types.html#solrcloud-mode a "Nodes" header that explains this be helpful?