SOLR-15730: Document SolrJ opt-in for 10x

[dsmiley]

See https://issues.apache.org/jira/browse/SOLR-15730?focusedCommentId=17603208&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-17603208

Added "Major changes in Solr 10".
Moved the "Upgrading 9.1" section to the page it should be on.

Someone please do a sanity check on the pages by rendering them locally. I believe this is via gradlew buildLocalSite. I can't get major-changes-in-solr-10.adoc to show up in the navigation; it's an orphaned page.

[janhoy]

One comment for 9.1 wording.

[janhoy]

As I understand, this will be a transitive dependency in Solr 9.1, so this text should say that no changes are needed as long as you enable automatic dependency resolution in maven/gradle.

[dsmiley]

Sure.

SolrJ is beginning to be split up. If you use ZooKeeper coordinates to create a CloudSolrClient, you will need to add a dependency on solrj-zookeeper. If you use SolrJ's Maven POM to depend on SolrJ, then this should happen automatically through transitive resolution.

[HoustonPutman]

Wait I'm confused, can you clear this up @janhoy ?

I thought that the solr-upgrade-notes.adoc was supposed to have the current major versions minor releases. Then that page will be migrated to major-changes-in-solr-10.adoc whenever Solr 10 is cut. Am I missing something?

[janhoy]

Wait I'm confused, can you clear this up @janhoy ?

I thought that the solr-upgrade-notes.adoc was supposed to have the current major versions minor releases. Then that page will be migrated to major-changes-in-solr-10.adoc whenever Solr 10 is cut. Am I missing something?

You are right, and I thought about it too. But then it is a bit confusing too. You proposed to change how we do all this, didn't you? Perhaps we shold do that soon?

[dsmiley]

Where we put notes on this has been confusing! I feel like it needs it's own developer documentation how-to!

[HoustonPutman]

Right now our docs are structured such that we are expecting users to upgrade from an outdated minor version to the x.0 release of the next version. To me it would be clearer to have it like David is doing, but then we kind of need to either change the page names (which is fine because we are on antora now) so that major-changes-in-solr-9.adoc forwards requests too solr-8-upgrade-notes.adoc and have all 8.0-8.11 notes there. So that the anchor to 9.0 in that current page is not broken, we can have a small section at the end that links to solr-9-upgrade-notes.adoc#9.0 or something like that.

At this point we won't need to do anything for a major release, and links stay consistent even when the major version is cut.
We can also trust people to look at all of the versions that they are skipping, even if it's on a different page.

I can try to hack something together tomorrow if y'all want to see it to completion after that.

[janhoy]

Cassandra documented partly how it's done here https://issues.apache.org/jira/browse/SOLR-15901
I think there used to be some meta-docs about this earlier too but I cannot find it now. We should probably establish a dev-docs document about how to maintain the ref-guide.

I'm all for a restructure on this. Then the solr-10-upgrade-notes will talk about what's new in Solr 10 and 10.x, and it will clearly state that users upgrading from earlier 9.x versions or even from 8.x will need to consult those pages, which seems logical.

[dsmiley]

The discussions are good but I think I can merge this finally, and back-port some aspects to branch_9x?

[HoustonPutman]

Go ahead and merge, we can fix these things separately