Great additional points Jan! I just wanted to get the ball rolling here. We can probably have an LLM take your points and integrate it into the wiki page.
+1 as well to your point Eric on "lucene.experimental" and "lucene.internal" On Fri, 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 > > > > 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 > >> > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
