[solr] branch branch_9_0 updated: SOLR-15780: Document v2 API as "experimental" (#849)

[ge...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

gerlowskija pushed a commit to branch branch_9_0
in repository https://gitbox.apache.org/repos/asf/solr.git


The following commit(s) were added to refs/heads/branch_9_0 by this push:
     new 28ef5f587d7 SOLR-15780: Document v2 API as "experimental" (#849)
28ef5f587d7 is described below

commit 28ef5f587d7791fe518053a3cf33347453b11677
Author: Jason Gerlowski <ge...@apache.org>
AuthorDate: Tue May 10 15:41:38 2022 -0400

    SOLR-15780: Document v2 API as "experimental" (#849)
    
    The community decided recently that the v2 API should be treated as
    "experimental", and exempt from strict adherence to
    backwards-compatibility requirements.
    
    This commit updates the v2-api.adoc page in the ref guide to include
    a caveat/warning about this, along with a corresponding note in
    CHANGES.txt.
---
 solr/CHANGES.txt                                                  | 3 +++
 solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc | 6 ++++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt
index 996e2ab4d1f..d327be78f7b 100644
--- a/solr/CHANGES.txt
+++ b/solr/CHANGES.txt
@@ -616,6 +616,9 @@ Other Changes
 
 * SOLR-16101: Add empty constructor for SolrInputDocument (Anshum Gupta)
 
+* SOLR-15780: The v2 API is now treated as "experimental".  It may change in backwards-incompatible ways in subsequent releases
+  as it expands to cover additional functionality and prepares to supplant the v1 API. (Jason Gerlowski)
+
 Bug Fixes
 ---------------------
 * SOLR-15849: Fix the connection reset problem caused by the incorrect use of 4LW with \n when monitoring zooKeeper status
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
index cafddbc9e7c..11dd8c11e56 100644
--- a/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
@@ -19,9 +19,11 @@
 [[top-v2-api]]
 The v2 API is a modernized self-documenting API interface covering most current Solr APIs.
 It is anticipated that once the v2 API reaches full coverage, and Solr-internal API usages like SolrJ and the Admin UI have been converted from the old API to the v2 API, the old API will eventually be retired.
+Today, the two API styles coexist, and all the old APIs will continue to work without any change.
+You can disable all v2 API endpoints if desired by starting your servers with this system property: `-Ddisable.v2.api=true`.
 
-For now the two API styles will coexist, and all the old APIs will continue to work without any change.
-You can disable all v2 API endpoints by starting your servers with this system property: `-Ddisable.v2.api=true`.
+NOTE: The v2 API is classified as "experimental".
+It may change in backwards-incompatible ways as it evolves to cover additional functionality.
 
 The old API and the v2 API differ in three principle ways: