We should include the fact that we do have this idea of “Experimental” that indicates “all bets are off” about an api. That was what we settled on for all the v2 APIs for now.
It would be nice to clarify the use of javadocs that say "This API is experimental and subject to change”, they are everywhere….. And the use of the @lucene.experimental annotation. What do they mean? Are they patterns to follow. Maybe this gets beyond deprecation, but it’s how we communicate to future consumers of Solr. > On Aug 21, 2026, at 10:36 AM, Jan Høydahl <[email protected]> wrote: > > I think any deprecation guideline should recognize that we have several > public APIs with a promise of non breaking change in minor versions. Java > code (APIs that 3rd party plugins may rely on) is one. REST APIs is another. > CLI tool options is yet another one, config-file format (schema.xml) is yet > another. Minimum Java version is an important one. Lucene-index-codec > back-compat should be another one but Lucene itself keep breaking binary > index format in minor versions so a downgrade of Solr from 9.11 to 9.7 e.g. > is impossible. That's a separate discussion. Zookeeper strucutre is NOT a > public contract, nor is internal APIs, and we explicitly do not promise > anything for things marked as lucene.experimental etc. > > Also the doc should cover how we deprecate non-Java contracts, i.e. through a > deprecation log, a WARN box in ref-guide etc. > > The primary rule should be no removal of any of the above mentioned public > contracts in minor versions. But with a good reason (such as we did for > Metrics and OTEL public contracts) we can make exceptions, which then gets a > prominent mention in Upgrade-Notes for the version and a retro-fitted > deprecation. > > Jan > > > 21. aug. 2026 kl. 15:41 skrev David Smiley <[email protected]>: > > > > Rough draft: > > https://cwiki.apache.org/confluence/spaces/SOLR/pages/449282850/Deprecation+Policy > > > > <https://cwiki.apache.org/confluence/spaces/SOLR/pages/449282850/Deprecation+Policy> > > > > On Fri, Aug 21, 2026 at 9:07 AM David Smiley <[email protected]> wrote: > > > >> Maybe we should have a written deprecation policy somewhere? > >> > >> Any way... copy-pasting what I wrote in a related thread: > >> > >> If we deprecated something on 10.0 and not 9.x because 9.x doesn't have > >> the new method/class, my instinct is that we may remove the thing at any > >> 10.x version (even 10.1) -- need not wait for 11. If we must wait for 11, > >> I think this imposes too much of a burden on us. > >> > >> I guess if folks disagree with my assertion above, committers may > >> nonetheless choose to delete in 10.x *anyway* provided that the > >> deprecated thing is "internal" (subjectively determined). For internal > >> things, in my strong opinion, the deprecation was a courtesy and/or is > >> equivalent to a TODO comment that can be accomplished at-will. We remove > >> interal methods at-will all the time without a deprecation or TODO!! > >> > >> ~ David Smiley > >> Apache Lucene/Solr Search Developer > >> http://www.linkedin.com/in/davidwsmiley > >> <http://www.linkedin.com/in/davidwsmiley> > >> > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] Disclaimer The information contained in this communication from the sender is confidential. It is intended solely for use by the recipient and others authorized to receive it. If you are not the recipient, you are hereby notified that any disclosure, copying, distribution or taking action in relation of the contents of this information is strictly prohibited and may be unlawful. This email has been scanned for viruses and malware, and may have been automatically archived by Mimecast, a leader in email security and cyber resilience. Mimecast integrates email defenses with brand protection, security awareness training, web security, compliance and other essential capabilities. Mimecast helps protect large and small organizations from malicious activity, human error and technology failure; and to lead the movement toward building a more resilient world. To find out more, visit our website.
