Thanks Jan :-) I love the idea of a dev-docs/deprecation.adoc, perhaps generalized to backwards compatibility in general.
On Wed, Nov 5, 2025 at 9:14 AM Jan Høydahl <[email protected]> wrote: > 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] > >
