Hi, I think it boils down to this: David has stepped up and done a tremendous job in improving SolrJ, and gets to choose how. We as spectators should applaude, not bike shed.
Bravo David! The general discussion about when/how to @Deprecate, javadoc @deprecate, shim, update ref-guide release-notes, add/remove @lucene.experimental etc is an interesting discussion, and is perhaps better had in a dedicated PR on a new dev-docs/deprecation.adoc document? Jan > 5. nov. 2025 kl. 14:39 skrev Gus Heck <[email protected]>: > > I think there may have been a misreading of my last message. I'm not > advocating that we should shim everything, my point is that deprecation as > a concept implies the existence of an alternative. Deprecation indicates > there is an action that the developer can take. I don't think we need > "deprecation" for every little API change. If we know something is going to > change and want to warn folks in advance we can mark it "@Unstable" or > "@Changing" or something like that (think of it as a sort of reversion to > @Experimental?). But we shouldn't be using "@Deprecated" (which creates IDE > warnings and invokes IT Policy) unless we are releasing an alternative > concurrently, or the functionality is disappearing entirely. In > every case @deprecated javadoc tag (or equivalent annotation/comment/etc) > should clearly describe for the developer what the replacement is and > possibly point to more information that will help the developer make the > transition (like the Jira ticket number or ref guide section?), before the > current method/class/etc becomes unavailable. > > Whether or not to shim (or simply maintain two versions of the code > simultaneously for a short time), so we can use @Deprecated is a matter of > magnitude, and impact. I don't think there's a hard rule there. > > -Gus > > On Wed, Nov 5, 2025 at 2:32 AM Piotr P. Karwasz <[email protected]> > wrote: > >> Hi Jan, >> >> On 5.11.2025 01:44, Jan Høydahl wrote: >>> It is more work to provide a rename or package move if you also need >>> to produce shims for the old behavior to work. And in SolrJ for v10 >>> we even re-use a previous class name for a differenet purpose, so >>> for such a change to work with deprecation we'd need to place the >>> new impl in a different package. No wonder some frameworks include >>> version in the package name. >> >> Including a version number in the package name is typically done when a >> library is used as a deeply nested transitive dependency, and consumers >> cannot migrate to the new version all at once. >> >> In such cases, you either include both the new classes and shims for the >> old ones in the same Maven module (case 5 in JLBP-6 [1]), or you change >> the Maven coordinates entirely (case 4). >> >> Projects like Commons, HttpClient, and Log4j follow this approach, but I >> don’t think it’s necessary for SolrJ. For instance, the Elasticsearch >> Java Client reorganized several classes in version 9.0.0 [2] without >> previous deprecations or shims for old classes. >> >> Piotr >> >> [1] https://jlbp.dev/JLBP-6 >> [2] >> https://www.elastic.co/docs/release-notes/elasticsearch/clients/java/9-0-0 >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [email protected] >> For additional commands, e-mail: [email protected] >> >> > > -- > http://www.needhamsoftware.com (work) > https://a.co/d/b2sZLD9 (my fantasy fiction book) --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
